針對 Azure Functions 中的 Python 錯誤進行疑難排解

本文提供的資訊可協助您針對 Azure Functions 中的 Python 函式錯誤進行疑難排解。 本文同時支援 v1 和 v2 程式設計模型。 從文章頂端的選取器中選擇所需的模型。

注意

僅在 4.x 函式執行階段中支援 Python 第 2 版程式設計模型。 如需詳細資訊，請參閱 Azure Functions 執行階段版本概觀。

以下為 Python 函式中常見問題的疑難排解章節：

• ModuleNotFoundError 和 ImportError
• 無法匯入「cygrpc」
• Python 已結束，代碼為 137
• Python 已結束，代碼為 139
• 失敗的同步觸發程序

特別是 v2 模型，以下是一些已知問題及其因應措施：

• 無法載入檔案或組件
• 無法解析名為儲存體的 Azure 儲存體連線

Python Functions 的一般疑難排解指南包括：

• ModuleNotFoundError 和 ImportError
• 無法匯入「cygrpc」
• Python 已結束，代碼為 137
• Python 已結束，代碼為 139
• 失敗的同步觸發程序
• Azure 入口網站中的開發問題

疑難排解：ModuleNotFoundError

此章節可協助您針對 Python 函式應用程式中的模組相關錯誤進行疑難排解。 這些錯誤通常會導致下列 Azure Functions 錯誤訊息：

例外狀況：ModuleNotFoundError：沒有名為 'module_name' 的模組。

當 Python 函式應用程式無法載入 Python 模組時，就會發生此錯誤。 此錯誤的根本原因是下列其中一個問題：

• 找不到套件
• 未使用適當的 Linux Wheel 來解析套件
• 套件與 Python 解譯器版本不相容
• 套件與其他套件發生衝突
• 套件僅支援 Windows 或 macOS 平台

檢視專案檔

若要識別出問題的實際原因，您需要取得在函式應用程式上執行的 Python 專案檔。 如果您的本機電腦上沒有專案檔，可以使用下列其中一種方式來取得：

• 如果函數應用程式具有 WEBSITE_RUN_FROM_PACKAGE 應用程式設定且其值為 URL，則可將 URL 複製並貼到瀏覽器，以下載檔案。
• 如果函數應用程式具有已設為 1 的 WEBSITE_RUN_FROM_PACKAGE，請前往 https://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackages，並從最新的 href URL 下載檔案。
• 如果函數應用程式不具上述任一應用程式設定，請前往 https://<app-name>.scm.azurewebsites.net/api/settings，並在 SCM_RUN_FROM_PACKAGE 底下尋找 URL。 藉由將 URL 複製並貼到瀏覽器來下載檔案。
• 如果這些建議能夠解決問題，請前往 https://<app-name>.scm.azurewebsites.net/DebugConsole 並檢視 /home/site/wwwroot 底下的內容。

此文章的其餘部分可協助您藉由檢查函式應用程式的內容、識別根本原因並解決特定問題，以針對此錯誤的可能原因進行疑難排解。

診斷 ModuleNotFoundError

此節將詳細說明模組相關錯誤的可能根本原因。 當您識別出可能的根本原因之後，即可移至相關的緩和措施。

找不到套件

移至 .python_packages/lib/python3.6/site-packages/<package-name> 或 .python_packages/lib/site-packages/<package-name>。 如果檔案路徑不存在，則這個遺失路徑可能就是根本原因。

部署期間使用協力廠商或過時的工具可能會導致此問題。

如需減輕此問題的影響，請參閱啟用遠端組建或建置原生相依性。

未使用適當的 Linux Wheel 來解析套件

移至 .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info 或 .python_packages/lib/site-packages/<package-name>-<version>-dist-info。 使用您慣用的文字編輯器來開啟 Wheel 檔案，然後檢查 Tag: 區段。 問題可能是標籤值不包含 linux。

Python 函式只會在 Azure 中的 Linux 上執行。 函式執行階段第 2.x 版會在 Debian Stretch 上執行，第 3.x 版執行階段會在 Debian Buster 上執行。 成品預期會包含正確的 Linux 二進位檔。 當您在核心工具、第三方或過時的工具中使用 --build local 旗標時，可能導致使用較舊的二進位檔。

如需減輕此問題的影響，請參閱啟用遠端組建或建置原生相依性。

套件與 Python 解譯器版本不相容

移至 .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info 或 .python_packages/lib/site-packages/<package-name>-<version>-dist-info。 在文字編輯器中，開啟 METADATA 檔案，並查看 [分類器：] 區段。 如果該區段不包含 Python :: 3、Python :: 3.6、Python :: 3.7、Python :: 3.8 或 Python :: 3.9，這表示套件版本可能太舊，或者很可能該套件已不在維護中。

您可以從 Azure 入口網站檢查函式應用程式的 Python 版本。 瀏覽至函數應用程式的 [概觀] 資源頁面，以尋找執行階段版本。 如 Azure Functions 執行階段概觀中所述，執行階段版本會支援 Python 版本。

如需減輕此問題的影響，請參閱將套件更新為最新版本或將套件取代為對等項目。

套件與其他套件發生衝突

如果您確認已正確使用適當的 Linux Wheel 來解析套件，則可能會與其他套件發生衝突。 在某些套件中，PyPi 文件可能會闡明不相容的模組。 例如，您會在 azure 4.0.0 中尋找下列陳述式：

此套件與 azure-storage 不相容。 如果您已安裝 azure-storage，或已安裝 azure 1.x/2.x 且未解除安裝 azure-storage，則必須先解除安裝 azure-storage。

您可以在 https://pypi.org/project/<package-name>/<package-version> 中找到套件版本的文件。

如需減輕此問題的影響，請參閱將套件更新為最新版本或將套件取代為對等項目。

此套件僅支援 Windows 或 macOS 平台

使用文字編輯器開啟 requirements.txt，並檢查 https://pypi.org/project/<package-name> 中的套件。 某些套件僅支援 Windows 或 macOS 平台。 例如，pywin32 只能在 Windows 上執行。

當您使用 Windows 或 macOS 進行本機開發時，可能不會發生 Module Not Found 錯誤。 不過，無法在執行階段使用 Linux 的 Azure Functions 上匯入套件。 這個問題可能是因為在專案初始化期間，使用 pip freeze 來將虛擬環境匯出至 Windows 或 macOS 機器的 requirements.txt 所致。

如需減輕此問題的影響，請參閱將套件取代為對等項目或製作 requirements.txt。

緩和 ModuleNotFoundError

以下是模組相關問題的可能緩和措施。 使用上述診斷來判斷要嘗試哪一個緩和措施。

啟用遠端組建

確定已啟用遠端組建。 確定的方式取決於部署方法。

Visual Studio Code

確定已安裝適用於 Visual Studio Code 的 Azure Functions 延伸模組的最新版本。 確認 .vscode/settings.json 檔案存在，且其中包含設定 "azureFunctions.scmDoBuildDuringDeployment": true。 如果不包含該設定，請在啟用 azureFunctions.scmDoBuildDuringDeployment 設定的情況下建立該檔案，然後重新部署專案。

Azure Functions Core Tools

確定已安裝最新版的 Azure Functions Core Tools。 移至您的區域函式專案資料夾，然後使用 func azure functionapp publish <app-name> 進行部署。

手動發佈

如果您手動將套件發佈至 https://<app-name>.scm.azurewebsites.net/api/zipdeploy 端點，請確保將 SCM_DO_BUILD_DURING_DEPLOYMENT 和 ENABLE_ORYX_BUILD 都設為 true。 若要深入了解，請參閱如何使用應用程式設定。

建置原生相依性

確定已安裝最新版的 Docker 和 Azure Functions Core Tools。 移至您的區域函式專案資料夾，然後使用 func azure functionapp publish <app-name> --build-native-deps 進行部署。

將套件更新為最新版本

在 https://pypi.org/project/<package-name> 中的最新套件版本中查看 [分類器：] 區段。 套件應該是 OS Independent，或與作業系統中的 POSIX 或 POSIX :: Linux 相容。 此外，程式設計語言應該包含：Python :: 3、Python :: 3.6、Python :: 3.7、Python :: 3.8 或 Python :: 3.9。

如果這些套件項目都正確，您就能透過變更 requirements.txt 中的 <package-name>~=<latest-version> 行，來將套件更新為最新版本。

製作 requirements.txt

有些開發人員會使用 pip freeze > requirements.txt，來產生可供其開發環境使用的 Python 套件清單。 雖然這在大部分案例中都應該可行，但可能會在跨平台部署案例中發生問題，例如，在 Windows 或 macOS 上本機開發函式，但要發佈到在 Linux 上執行的函式應用程式。 在此案例中，pip freeze 可能會為您的本機開發環境引進非預期的作業系統特定相依性或相依性。 這些相依性可能會在 Linux 上執行時中斷 Python 函數應用程式。

最佳做法是在專案原始程式碼中檢查每個 .py 檔案的匯入陳述式，並且只在 requirements.txt 檔案中簽入那些模組。 這麼做能保證在不同作業系統上都能正確處理套件的解析。

將套件取代為對等項目

首先，請在 https://pypi.org/project/<package-name> 中查看套件的最新版本。 此套件通常有自己的 GitHub 頁面。 前往 GitHub 上的 [問題] 區段，並搜尋以查看問題是否已修正。 如已修正，則將套件更新為最新版本。

有時，套件可能已整合到 Python 標準程式庫 (例如 pathlib)。 若是如此，由於我們會在 Azure Functions 中提供特定的 Python 發行版本 (Python 3.6、Python 3.7、Python 3.8 和 Python 3.9)，因此 requirements.txt 檔案中的套件應會遭移除。

不過，如果您發現問題尚未修正，而且期限將至，建議您做一些研究，以尋找專案適用的類似套件。 Python 社群通常將為您提供可使用的各種類似程式庫。

停用相依性隔離旗標

將應用程式設定 PYTHON_ISOLATE_WORKER_DEPENDENCIES 設為 0 值。

---

疑難排解：無法匯入 'cygrpc'

此章節可協助您針對 Python 函數應用程式中的 'cygrpc' 相關錯誤進行疑難排解。 這些錯誤通常會導致下列 Azure Functions 錯誤訊息：

無法從 'grpc._cython' 匯入名稱 'cygrpc'

當 Python 函數應用程式無法以適當的 Python 解譯器開始時，即會發生此錯誤。 此錯誤的根本原因是下列其中一個問題：

• Python 解譯器不符合 OS 結構
• Azure Functions Python 背景工作角色不支援 Python 解譯器

診斷 'cygrpc' 參考錯誤

本節會詳述參考 cygrpc 之錯誤的數個可能原因。

Python 解譯器不符合 OS 結構

此不相符可能是因為您在 64 位元作業系統上安裝 32 位元 Python 解譯器之緣故。

如果您在 x64 作業系統上執行，請確定 Python 3.6、3.7、3.8 或 3.9 版的解譯器也是 64 位元版本。

您可以透過下列命令來檢查 Python 解譯器位元：

在 PowerShell 的 Windows 上，執行 py -c 'import platform; print(platform.architecture()[0])'。

在類似 Unix 的殼層上，執行 python3 -c 'import platform; print(platform.architecture()[0])'。

如果 Python 解譯器位元與作業系統結構不符，請從 Python Software Foundation 下載適當的 Python 解譯器。

Azure Functions Python 背景工作角色不支援 Python 解譯器

Azure Functions Python 背景工作角色僅支援特定 Python 版本。

請檢查 Python 解譯器是否符合 Windows 中的 py --version 或類似 Unix 系統中的 python3 --version 所預期版本。 請確定傳回結果為其中一個支援的 Python 版本。

如果 Python 解譯器版本不符合 Azure Functions 的需求，請從 Python Software Foundation 下載 Functions 所支援的 Python 解譯器版本。

---

疑難排解：使用代碼 137 結束的 Python

程式碼 137 錯誤通常是因為 Python 函式應用程式中的記憶體不足問題所造成。 因此，會出現下列 Azure Functions 錯誤訊息：

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException：使用代碼 137 結束的 Python

當使用 SIGKILL 訊號的作業系統強制終止 Python 函數應用程式時，就會發生此錯誤。 此訊號通常表示 Python 流程中的記憶體不足錯誤。 Azure Functions 平台有服務限制，將會終止任何超過此限制的函數應用程式。

若要分析函數應用程式中的記憶體瓶頸，請參閱在本機開發環境中分析 Python 函數應用程式。

---

疑難排解：使用代碼 139 結束的 Python

此章節可協助您針對 Python 函式應用程式中的分割錯誤進行疑難排解。 這些錯誤通常會導致下列 Azure Functions 錯誤訊息：

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException：使用代碼 139 結束的 Python

當使用 SIGSEGV 訊號的作業系統強制終止 Python 函數應用程式時，就會發生此錯誤。 此訊號表示記憶體分割違規，這可能是因為從受限制的記憶體區域意外讀取或寫入至受限制記憶體區域所造成。 在下列各節中，我們會提供常見的根本原因清單。

協力廠商套件的迴歸

在函數應用程式的 requirements.txt 檔案中，取消釘選的套件將會在每個 Azure 部署期間升級至最新版本。 套件更新可能會導致迴歸，而對應用程式造成影響。 若要排除這類問題，請嘗試註解化匯入陳述式、停用套件參考，或將套件釘選到 requirements.txt 中的舊版。

從格式錯誤的 .pkl 檔案中取消點選

如果函數應用程式使用 Python 選擇器程式庫，從 .pkl 檔案載入 Python 物件，則 .pkl 可能包含格式錯誤的位元組字串，或包含不正確位址參考。 若要排除此問題，請嘗試註解化 pickle.load() 函式。

Pyodbc 連線衝突

如果函數應用程式使用熱門的 ODBC 資料庫驅動程式 pyodbc，則可能會在單一函數應用程式內開啟多個連線。 若要避免這個問題，請使用單一資料庫模式，並確保函數應用程式之間只使用一個 pyodbc 連線。

---

失敗的同步觸發程序

錯誤 Sync triggers failed 可能是由數個問題所造成。 其中一個潛在原因是，當函式在 App Service 方案中執行時，客戶定義的相依性和 Python 內建模組之間發生衝突。 如需詳細資訊，請參閱封裝管理。

---

疑難排解：無法載入檔案或組件

當您使用第 2 版程式設計模型在本機執行時，可能會看到此錯誤。 此錯誤是由已知問題造成，將於近期版本中解決此錯誤。

這是此錯誤的範例訊息：

DurableTask.Netherite.AzureFunctions：無法載入檔案或組件 'Microsoft.Azure.WebJobs.Extensions.DurableTask、Version=2.0.0.0, Culture=neutral、PublicKeyToken=014045d636e89289'。
系統找不到指定的檔案。

發生此錯誤的原因是，延伸模組特件組合如何快取的相關問題。 若要針對問題進行疑難排解，請使用 --verbose 執行此命令，以查看更多詳細資料：

func host start --verbose

當您看到延伸模組載入記錄 (例如 Loading startup extension <>，後面沒有接 Loaded extension <>) 時，可能會看到此快取問題。

若要解決此問題：

1. 執行下列項目以尋找 .azure-functions-core-tools 路徑：

   func GetExtensionBundlePath
   

2. 刪除 .azure-functions-core-tools目錄。

   Bash

   rm -r <insert path>/.azure-functions-core-tools
   

   PowerShell

   Remove-Item <insert path>/.azure-functions-core-tools
   

   Cmd

   rmdir <insert path>/.azure-functions-core-tools
   

當您再次執行核心工具時，系統便會重新建立快取目錄。

疑難排解：無法解析 Azure 儲存體連線

如下列訊息所示，您可能會在本機輸出中看到此錯誤：

Microsoft.Azure.WebJobs.Extensions.DurableTask：無法解析名為 'Storage' 的 Azure 儲存體連線。
值不可以是 null。 (參數 'provider')

此錯誤是在如何本機從套件組合載入延伸模組的結果。 若要解決這個錯誤，請執行下列任一動作：

• 使用儲存體模擬器，例如 Azurite。 當您不打算在函數應用程式中使用儲存體帳戶時，這是不錯的選項。

• 建立儲存體帳戶，並將連接字串新增至 localsettings.json 檔案中的 AzureWebJobsStorage 環境變數。 當您使用儲存體帳戶觸發程序或與應用程式繫結時，或如果您有現有的儲存體帳戶，請使用此選項。 若要開始使用，請參閱建立儲存體帳戶。

部署後找不到函式

有幾個常見的建置問題可能會導致在看似成功的部署後主機找不到 Python 函式：

• 代理程式集區必須在 Ubuntu 上執行，以確保套件從建置步驟正確還原。 確保您的部署範本需要 Ubuntu 環境來建置和部署。

• 當函式應用程式不在來源存放庫的根目錄時，請確保 pip install 步驟會參考用來建立 .python_packages 資料夾的正確位置。 請記住，此位置會區分大小寫，例如在此命令範例中：

  pip install --target="./FunctionApp1/.python_packages/lib/site-packages" -r ./FunctionApp1/requirements.txt
  

• 該範本必須產生一個可以載入到 /home/site/wwwroot 中的部署套件。 在 Azure Pipelines 中，這會由 ArchiveFiles 工作完成。

Azure 入口網站中的開發問題

使用 Azure 入口網站時，請考慮下列已知問題及其因應措施：

• 在入口網站中撰寫函式程式碼存在一般限制。 如需詳細資訊，請參閱 Azure 入口網站中的開發限制。

• 若要從入口網站中的函數應用程式刪除函式，請從檔案本身移除函式程式碼。 使用 Python 第 2 版程式設計模型時，刪除按鈕無法移除函式。

• 在入口網站中建立函式時，您可能會收到建議，建議您使用不同的工具進行開發。 在某些情節中，您無法在入口網站中編輯程式碼 (包括偵測到語法錯誤時)。 在這些情節中，請使用 Visual Studio Code 或 Azure Functions Core Tools 來開發和發佈函式程式碼。

下一步

如果您無法解決問題，請聯絡 Azure Functions 小組：

回報未解決的問題