這篇教學要講的是一個很常混在一起的觀念：
– `os.environ[“PATH”]`
– `sys.path.append(…)`
很多人第一次看到這兩個，都會覺得：
– 反正都是 path
– 反正都是在「讓程式找得到東西」
– 看起來只差一個是 `os.environ`，一個是 `sys.path`
但它們其實不在同一層。
最簡單的一句話是：
– `os.environ[“PATH”]`：讓作業系統找「可執行檔」
– `sys.path`：讓 Python 找「可 import 的東西」，
白話講通常就是 `.py` 檔，
或一個可被當成模組資料夾的目錄
（最常見是裡面有 `__init__.py`）
## 先用 Whisper + ffmpeg 這個例子理解
這個例子很適合，因為它剛好同時碰到兩層：
1. `whisper` 本身是一個 Python 模組
2. `ffmpeg.exe` 是一個外部可執行檔
所以你可能會遇到兩種完全不同的錯誤。
### 情況 A：Python 找不到 `whisper`
例如：
“`python
import whisper
“`
結果報：
“`text
ModuleNotFoundError: No module named ‘whisper’
“`
這代表：
– Python 解譯器找不到 `whisper` 這個模組
– 這通常是 interpreter、虛擬環境、site-packages、`sys.path` 這一層的問題
### 情況 B：`whisper` 可以 import，但跑起來找不到 `ffmpeg.exe`
例如 `whisper` 已經能 import，
但執行轉音訊時，底層 subprocess 找不到 `ffmpeg`。
這時問題通常不是 `sys.path`，而是：
– 作業系統找不到 `ffmpeg.exe`
– 也就是「作業系統搜尋可執行檔的路徑（PATH）」這一層有問題
所以同樣都是「找不到」，
但其實是兩種完全不同的找法。
## `os.environ[“PATH”]` 在做什麼
`os.environ[“PATH”]` 對應的是作業系統層的搜尋路徑。
當你在終端機輸入：
“`text
python
pip
git
ffmpeg
“`
系統會去 `os.environ[“PATH”]` 裡列出的資料夾，
一個一個找對應的執行檔。
所以它主要解決的是：
– `ffmpeg.exe` 找不找得到
– `python.exe` 找不找得到
– `pip.exe` 找不找得到
例如：
“`python
import os
print(os.environ[“PATH”])
“`
你看到的通常會是一大串資料夾路徑。
### 臨時把 `ffmpeg\bin` 加進 PATH
“`python
import os
ffmpeg_bin_path = r”C:\ffmpeg\bin”
os.environ[“PATH”] = ffmpeg_bin_path + os.pathsep + os.environ[“PATH”]
“`
注意：這裡加進 `os.environ[“PATH”]` 的是
`C:\ffmpeg\bin` 這個資料夾，
不是 `C:\ffmpeg\bin\ffmpeg.exe` 這個檔案本身。
這裡特別把 `ffmpeg_bin_path` 放在前面，
不是單純寫法習慣，
而是為了讓這個目錄裡的 `ffmpeg.exe` 取得更高優先權。
也就是說，系統之後找 `ffmpeg.exe` 時，會先找：
– `C:\ffmpeg\bin`
– 再找原本 `os.environ[“PATH”]` 裡既有的那些目錄
這在電腦上同時存在多個版本的
`ffmpeg.exe`、`dot.exe`、`python.exe` 時很有用。
如果你改寫成下面這種：
“`python
os.environ[“PATH”] += os.pathsep + ffmpeg_bin_path
“`
那就會變成把新路徑加到最後面。
這種寫法不是不能用，而是優先權比較低：
– 前面原本 PATH 裡如果已經有另一個 `ffmpeg.exe`
– 系統通常會先找到舊的那個
– 你剛加進去的版本反而不一定會被用到
所以：
– 把新路徑放前面：表示「先用我指定的這個版本」
– 把新路徑加到後面：表示「前面都找不到時再用我」
這樣做的效果是：
– 只在目前這個 Python 程序中暫時生效
– 讓這個程序之後啟動的子程序，
也能比較容易找到 `ffmpeg.exe`
這裡刻意用：
“`python
os.pathsep
“`
而不是直接硬寫 `;`。
因為：
– Windows 的 path 分隔符是 `;`
– Linux / macOS 是 `:`
所以 `os.pathsep` 比較穩。
## `sys.path.append(…)` 在做什麼
`sys.path` 是 Python 解譯器用來找模組的路徑清單。
當你寫：
“`python
import my_utils
“`
Python 不看 `os.environ[“PATH”]`，它看的是：
“`python
import sys
print(sys.path)
“`
也就是：
– 目前工作目錄
– 標準函式庫
– site-packages
– 你手動 append 的資料夾
所以它主要解決的是：
– `import whisper` 找不找得到
– `import my_utils` 找不找得到
– `import project.helpers` 找不找得到
### 臨時把自訂模組目錄加進 `sys.path`
“`python
import sys
sys.path.append(r”D:\user\Python\my_project\src”)
“`
這樣做的效果是：
– 只在目前這個 Python 程序中暫時生效
– 讓 Python 之後可以從這個目錄 import 模組
## 兩者最核心的差別
如果只用一句話區分：
– `os.environ[“PATH”]` 找的是 executable
– `sys.path` 找的是 Python module
你也可以用下面這個對照表記住。
## 為什麼這兩個看起來很像
因為它們有三個共同點：
1. 都是一串路徑
2. 都是在「找東西」
3. 都可以在程式執行時暫時修改
所以很容易被誤認成同一件事。
但它們的搜尋對象不同：
– `os.environ[“PATH”]` 是給系統找程式
– `sys.path` 是給 Python 找模組
## `No module named …` 一般優先看什麼
如果錯誤是：
“`text
ModuleNotFoundError: No module named ‘xxx’
“`
一般優先檢查這些：
1. VS Code / Notebook 選到的 interpreter 是否正確
2. 套件是否真的安裝在那個 interpreter 對應的環境
3. 專案結構是否正確
4. 啟動方式是否合理，例如要不要用 `python -m package.module`
5. 是否只是編輯器分析錯誤，需要 `python.analysis.extraPaths`
不是先去改 `os.environ[“PATH”]`。
## `ffmpeg not found` 一般優先看什麼
如果是 `whisper` 類似工具能 import，
但執行時找不到 `ffmpeg`，那優先看的是：
1. `ffmpeg.exe` 是否真的存在
2. 它的 `bin` 目錄是否在系統 PATH 裡，也就是目前程序看到的 `os.environ[“PATH”]` 裡
3. 目前 Python 程式是否有把 `ffmpeg_bin_path` 臨時加進 `os.environ[“PATH”]`
這時通常不是 `sys.path` 的問題。
## 除了 `ffmpeg.exe`，還有哪些常見的 PATH 類外部工具？
如果 Python 套件本身可以 import，
但執行時還要再呼叫外部工具，
那常常就是 `os.environ[“PATH”]` / 系統 PATH 這一層。
比較常見、也很適合拿來理解的例子有：
– `ffmpeg.exe`
– `graphviz.exe`（很多時候實際缺的是 `dot.exe`）
– `dot.exe`
– `tesseract.exe`
– `pandoc.exe`
– `git.exe`
其中前面幾個最典型：
– `ffmpeg.exe`：影音轉檔、Whisper、moviepy、pydub
– `graphviz.exe` / `dot.exe`：流程圖、依賴圖、Graphviz 輸出
– `tesseract.exe`：OCR，常見於 `pytesseract`
### PaddleOCR 算不算這一類？
通常不算典型的 `os.environ[“PATH”]` 類外部 exe 依賴。
因為 PaddleOCR 比較常見的依賴是：
– `paddleocr`
– `paddlepaddle`
– GPU / CUDA / cuDNN
– DLL 或底層 runtime
– 模型檔
也就是說，PaddleOCR 比較常見的是 Python 套件與 runtime 依賴，
不是像 `tesseract.exe` 那樣，先去系統 PATH 裡找一個外部執行檔。
## `sys.path.append(…)` 能不能用
可以，但通常是臨時補丁，不是最漂亮的正式解法。
它適合：
– notebook
– 快速測試
– 一次性腳本
– 臨時驗證模組路徑
不太適合：
– 長期正式專案
– 多人協作
– 結構已固定的 package 專案
因為它會讓 import 規則散落在程式內部。
## `os.environ[“PATH”]` 能不能在程式內改
可以，但同樣屬於程序內暫時修補。
例如：
“`python
import os
ffmpeg_bin_path = r”C:\ffmpeg\bin”
os.environ[“PATH”] = ffmpeg_bin_path + os.pathsep + os.environ[“PATH”]
“`
這種做法很適合：
– 單一腳本
– notebook
– 臨時測試
– 你知道某個外部工具只差最後一步路徑沒接上
但如果是正式環境，通常更建議：
– 直接把 `ffmpeg\bin` 加到系統 PATH
– 讓所有終端機 / 工具都能共用
## 這個例子裡的三層關係
拿 `whisper` 當例子，可以把整件事拆成三層：
### 第 1 層：VS Code / Notebook 選哪個 Python
這一層常和：
– `python.defaultInterpreterPath`
– 實際選到的 interpreter
有關。
如果這裡就選錯了，後面很多事情都會錯。
### 第 2 層：Python 能不能 import 模組
這一層常和：
– site-packages
– `sys.path`
– 專案結構
有關。
例如：
– `import whisper`
– `import my_utils`
### 第 3 層：被呼叫的外部工具能不能被系統找到
這一層常和：
– `os.environ[“PATH”]`
– 系統環境變數 PATH
有關。
例如：
– `ffmpeg.exe`
– `git.exe`
– `pandoc.exe`
## 最實用的一句判斷
如果你看到的是：
“`text
No module named …
“`
先想：
– 這是 Python 找模組失敗
– 優先看 interpreter、環境、`sys.path`
如果你看到的是：
“`text
ffmpeg not found
“`
先想：
– 這是系統找可執行檔失敗
– 優先看 `os.environ[“PATH”]` / 系統 PATH
## 最後一句話
`os.environ[“PATH”]` 和 `sys.path` 看起來都像「路徑清單」，
但它們分別服務兩個不同世界：
– `os.environ[“PATH”]` 是作業系統的世界
– `sys.path` 是 Python import 的世界
用 `whisper` 與 `ffmpeg` 這個例子去記，通常最不容易搞混：
– `whisper` 是 module，所以偏 `sys.path`
– `ffmpeg.exe` 是 executable，所以偏 `os.environ[“PATH”]`
推薦hahow線上學習python: https://igrape.net/30afN