Python 基礎概念：執行 .py 檔與 shebang 用法

簡介

在學習 Python 時，最常見的第一步就是把寫好的程式碼存成 .py 檔，再讓電腦執行它。看似簡單的「執行檔」背後，其實隱藏了作業系統、環境變數與執行權限等多層機制。若不了解這些細節，常會碰到「找不到 Python」或「Permission denied」之類的錯誤，讓開發流程卡關。

而 shebang（又稱「哈希邦」）則是一行放在檔案最前面的特殊註解，它告訴 Unix-like 系統這個檔案應該交給哪個解譯器執行。掌握 shebang 的寫法與使用時機，能讓你的腳本在 Linux、macOS 甚至 Windows Subsystem for Linux (WSL) 上直接以 ./myscript.py 方式執行，提升開發效率與腳本可移植性。

本文將從 基本執行方式、shebang 語法、實務範例、常見陷阱，一步步帶你建立完整的執行觀念，讓你在日常開發與自動化任務中，能夠自信地使用 Python 腳本。

核心概念

1. 直接呼叫 Python 解譯器

最傳統、最保險的執行方式是：

python my_script.py

或在 Python 3 為主的環境中使用 python3：

python3 my_script.py

Tip：在多版本 Python 共存的系統上，務必確認使用的指令對應正確的版本，避免因語法差異產生錯誤。

範例 1：印出 Hello World

# hello.py
print("Hello, World!")  # 輸出訊息到終端機

執行方式：

python hello.py
# 或
python3 hello.py

2. 讓 .py 檔具備執行權限

在 Linux/macOS 中，檔案本身需要 執行權限 才能直接以 ./script.py 方式跑：

chmod +x my_script.py   # 加上執行權限
./my_script.py           # 直接執行

注意：若沒有正確設定 shebang，系統會無法判斷使用哪個解譯器，會出現 Exec format error。

3. shebang（#!）的基本語法

shebang 必須是檔案的 第一行，格式為：

#!/path/to/interpreter [optional-arg]

#! 開頭告訴 kernel 這是一個腳本檔。
/path/to/interpreter 必須是 絕對路徑。
之後的參數（如 -u、-E）是可選的。

常見 shebang 範例

作業系統	shebang 範例	說明
Linux/macOS	`#!/usr/bin/env python3`	使用 `env` 依照 `$PATH` 找到的 `python3`，最具可移植性。
Linux (特定路徑)	`#!/usr/local/bin/python3`	直接指定安裝路徑，適合已知環境。
Windows (WSL)	`#!/usr/bin/python3`	WSL 中仍遵循 Unix 標準。

4. 使用 `#!/usr/bin/env` 的好處

env 會根據 使用者的 $PATH 變數去搜尋可執行檔，優點包括：

跨平台：不同 Linux 發行版或 macOS 的 Python 安裝路徑可能不同，env 能自動適配。
虛擬環境相容：當你啟動 venv 或 conda 時，python 會指向虛擬環境內的解譯器，腳本自動使用正確版本。
維護成本低：不需要每次改動 shebang，只要調整 $PATH 即可。

範例 2：使用 env 的 shebang

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

"""
這是一個示範腳本，說明如何使用 shebang + env。
"""

def main():
    import sys
    print(f"Python 版本: {sys.version.split()[0]}")
    print("執行成功！")

if __name__ == "__main__":
    main()

執行步驟：

chmod +x demo_env.py
./demo_env.py

5. 兼容 Windows 的 shebang

Windows 本身不會解讀 shebang，但 py 啟動器（隨 Python 安裝）會支援：

py -3 demo_env.py

若在 Windows 上直接雙擊 .py 檔，系統會以註冊的 Python 解譯器開啟。因此，只要 安裝 Python 時勾選「Add Python to PATH」，大部分情況下都能直接執行。

範例 3：跨平台腳本

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import platform

def show_info():
    print("作業系統:", platform.system())
    print("Python 版本:", platform.python_version())

if __name__ == "__main__":
    show_info()

在 Linux/macOS：./cross_platform.py
在 Windows（WSL 或 CMD）：py cross_platform.py

6. 在虛擬環境中使用 shebang

假設你已建立 venv：

python3 -m venv myenv
source myenv/bin/activate   # Linux/macOS
# .\myenv\Scripts\activate   # Windows PowerShell

此時 $PATH 會把虛擬環境的 python 放在最前面，#!/usr/bin/env python3 會自動指向 虛擬環境內的 Python，不必額外修改 shebang。

範例 4：虛擬環境腳本

#!/usr/bin/env python3
import sys

def list_packages():
    """列出目前虛擬環境已安裝的套件"""
    import pkg_resources
    for dist in pkg_resources.working_set:
        print(f"{dist.project_name}=={dist.version}")

if __name__ == "__main__":
    print("使用的 Python:", sys.executable)
    list_packages()

執行前先啟動虛擬環境，然後：

chmod +x venv_script.py
./venv_script.py

常見陷阱與最佳實踐

陷阱	說明	改善方式
shebang 使用絕對路徑 (`#!/usr/bin/python3`)	在不同機器或容器中路徑可能不存在。	改用 `#!/usr/bin/env python3`，或使用相對於虛擬環境的路徑。
忘記加執行權限 (`chmod +x`)	直接執行會得到 `Permission denied`。	在腳本完成後立即 `chmod +x`，或在部署腳本中加入此指令。
Windows 不支援 shebang	直接雙擊會忽略第一行，導致預期行為不發生。	使用 `py` 啟動器或在 Windows 上設定檔案關聯；或在 README 中說明跨平台執行方式。
編碼問題 (`UnicodeDecodeError`)	預設使用 ASCII，中文註解或字串會失敗。	在檔案開頭加入 `# -- coding: utf-8 --`，或在 Python 3 中直接使用 UTF‑8（預設）+ `PYTHONIOENCODING=utf-8`。
使用舊版 Python	`python` 可能指向 2.x，導致語法錯誤。	明確使用 `python3` 或在 shebang 指定 `python3`，並在 CI 中檢查版本。

最佳實踐

統一使用 #!/usr/bin/env python3，確保跨平台與虛擬環境相容。
在腳本首行加入編碼宣告（UTF‑8），防止中文或特殊字元問題。
將腳本加入版本控制 時，確保 chmod +x 的設定也寫入 git（使用 git update-index --chmod=+x file.py）。
在 CI/CD pipeline 中加入測試，驗證腳本在不同 OS 上均能正確執行。
使用 __main__ guard (if __name__ == "__main__":) 讓腳本同時支援作為模組被 import 的情況。

實際應用場景

自動化部署腳本
- 透過 #!/usr/bin/env python3 撰寫部署工具，結合 subprocess 呼叫 git、docker，在 CI 中直接執行。
系統管理與監控
- 用 Python 撰寫日誌輪替、磁碟使用率檢查等腳本，放在 /usr/local/bin，賦予執行權限後即可在終端機直接呼叫。
資料前處理
- 大量 CSV 轉換或資料清理腳本，使用虛擬環境封裝依賴，透過 shebang 保證在不同開發機或伺服器上執行一致。
跨平台 CLI 工具
- 例如 mycli.py 包含 argparse 解析指令，使用 #!/usr/bin/env python3 讓使用者在 Linux、macOS、WSL 甚至 Windows（配合 py）都能直接使用 mycli 命令。
教育與示範
- 課堂上示範的程式碼可直接以 ./example.py 執行，免除每次都要打 python，提升教學流暢度。

總結

執行 .py 檔案不只是「打 python file.py」那麼簡單。透過 shebang 與 執行權限 的正確配置，你可以：

跨平台（Linux、macOS、Windows）無縫執行腳本
自動使用虛擬環境，保持依賴一致性
簡化指令，直接以 ./script.py 呼叫，提高開發與部署效率

在實務開發中，建議 統一採用 #!/usr/bin/env python3 作為 shebang，並在腳本開頭加入 UTF‑8 編碼宣告。配合 chmod +x、if __name__ == "__main__": 的良好結構，便能寫出既可讀、又 可搬移 的 Python 腳本，為日後的自動化與系統管理打下堅實基礎。祝你在 Python 的世界裡寫出更多好用的腳本！