流程執行的疑難排解

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

如果您的管線執行無法完成，請使用管線執行摘要頁面上的診斷資訊和記錄，針對問題進行疑難解答。本指南提供使用記錄、錯誤分析工具和常見疑難解答技術診斷管線失敗的指示。瞭解如何找出根本原因並實施解決方案，以保持您的管線暢通運行。

檢視記錄

選取錯誤訊息以檢視未完成之工作的記錄。

管線執行摘要頁面上工作錯誤訊息的螢幕快照。

日誌頁面會顯示選取的錯誤。在這裡範例中 cmd-line ，工作中發生錯誤，其中 echo 命令會輸入為 ech。

您可以選擇檢視原始日誌來查看任務的原始日誌，並使用尋找功能來搜索日誌內容。

日誌檢視選項的截圖在 Azure DevOps 中顯示。

掃描失敗工作的記錄，以取得錯誤資訊和工作失敗原因的線索。根據預設，管線執行會產生非驗證記錄。如果預設記錄未指出問題的原因，您可以透過設定詳細記錄來取得更多資訊。

錯誤分析頁面

使用 [錯誤分析 ] 頁面提供疑難解答協助。將滑鼠移至錯誤資訊行上方，然後選擇 [ 檢視分析 ] 圖示。

Azure DevOps Server 的視圖分析圖示截圖。

針對自我裝載 代理程式選擇 [檢視代理程式 ] （或[關於裝載Microsoft代理程式的代理程式映射 ]，以檢視用來執行管線之代理程式的詳細資訊，以及檢視記錄以檢視管線執行記錄。

Azure DevOps入口網站錯誤分析頁面截圖。

選擇運行 時間詳細數據 下方的工作名稱，以檢視工作的相關信息。

錯誤分析中工作詳細數據的螢幕快照。

在此範例中，您可以看到Value的Script中有錯誤。選擇 [關於此工作 ] 以檢視工作的檔。

如果在管線執行摘要頁面或瀏覽日誌中沒有發現問題，可檢查下列「常見問題」章節，並參閱「檢閱日誌來診斷管線問題」以了解如何下載完整日誌，這些日誌含有更多診斷資訊。

失敗管線運行的任務分析

Azure DevOps 提供一個 Task Insights for Failed Pipeline Runs 設定，啟用後會彈出建置失敗通知並附有連結以查看報告。

任務深入洞察指標的螢幕快照。

若要設定此設定，請流覽至 [預覽功能]，尋找 [失敗管線執行的工作深入解析]，然後選擇所需的設定。

失敗管線執行設定的工作深入解析螢幕快照。

失敗執行的通知

Azure DevOps 內建了針對失敗管線執行的通知功能。若要啟用通知：

移至 專案的 [項目設定>通知 ]。
選擇您想要接收的通知類型。若要在管線執行失敗時收到通知，請選取 [建置失敗]。

項目設定中通知的螢幕快照。

此管線需要存取資源的許可權，才能繼續執行

如果您的管線未能啟動，或您收到像 This pipeline needs permission to access a resource before this run can continue 這樣的錯誤訊息，請檢查管線是否正在等待由資源授予的執行授權，例如服務連接或代理池。

移至管線並手動啟動執行。
此訊息顯示此管線需要權限才能繼續執行，避免於執行過程中存取資源。選取 訊息旁的 [檢視 ]。
在 [ 等候檢閱] 畫面上，選取 [ 允許]，然後在確認畫面上，再次選取 [ 允許 ]。

此動作會將管線明確新增為資源的授權使用者。

有兩種方式可授權管線存取代理程式集區。

授權特定管線 - 個別授權Azure DevOps專案的特定管線在池中運行。
設定開啟存取 - 將專案層級的代理程式集區設定為可供該專案中的所有管線使用。

授權特定管線

您可以依照上一節中的程式，在收到類似 This pipeline needs permission to access a resource before this run can continue的訊息時，個別授權特定管線在代理程式集區中執行。

您也可以執行下列程式，從授權清單中手動新增和移除管線。此程序在您的 Azure DevOps 組織中，於專案層級執行。

在Azure DevOps中，前往 Project settings，Agent pools，選擇你的自架池，並選擇 Security。
選擇 + 將管線新增至授權清單。
選擇 [X（撤銷存取權] 以從授權清單中移除管線。

設定開啟存取

某些資源可讓您設定 開放存取 ，讓每個新的管線定義不需要明確授權。

設定 [開啟存取 權] 需要專案管理員許可權。

若要設定代理程式集區的 開放存取 ：

在Azure DevOps中，前往 Project settings，Agent pools，選擇你的自架池，並選擇 Security。
選擇 [其他動作]、[ 開啟存取權] 以啟用開啟存取權，然後選擇 [再次 開啟存取 ] 以確認。
若要撤銷開啟存取權，請選擇 [ 限制許可權]。

欲檢視其他資源類型是否可用開放取用，請參閱Azure Pipelines中的安全管理，並搜尋開放取用。

如需代理程式集區開放存取的詳細資訊，請參閱為個別代理程式集區設定管線許可權和管線許可權。

作業逾時

流程可以長時間執行，然後因為工作逾時而失敗。工作逾時很大程度上取決於所使用的代理。免費 Microsoft 裝載的代理程式針對私人存放庫，每個作業的逾時上限為 60 分鐘，而公用存放庫的逾時上限為 360 分鐘。

若要增加作業的逾時上限，您可以選擇下列任何一項。

購買一個由 Microsoft 託管的代理，這可提供您所有作業共 360 分鐘的執行時間，無論使用的存放庫是什麼。
使用自我裝載代理程式來排除因代理程式造成的任何逾時問題

深入了解作業逾時。

備註

如果您使用由 Microsoft 裝載的代理程式作業出現逾時，請確認您的管線逾時設定值大於作業的最大逾時限制。若要檢查，請參閱逾時。

下載程式碼時發生問題

我的管線在簽出步驟時失敗
Team Foundation 版本控制（TFVC）問題

我的管線在簽出步驟時失敗

如果你在組織中使用 checkout 步驟，並且該 Azure Repos Git 存儲庫位於與你的管線不同的專案中，請確保已關閉 限制作業授權範圍至目前專案設定，或按照 Scoped 建構身份中的步驟，確保你的管線能夠存取該存儲庫。

當管線因為作業授權範圍有限而無法存取儲存庫時，您會收到錯誤 Git fetch failed with exit code 128 ，而且您的記錄包含相似的項目 Remote: TF401019: The Git repository with name or identifier <your repo name> does not exist or you do not have permissions for the operation you are attempting.

如果您的管線立即失敗， Could not find a project that corresponds with the repository請確定您的專案和存放庫名稱在步驟或存放庫資源宣告中 checkout 正確無誤。

Team Foundation 版本控制（TFVC）問題

取得未下載某些檔案的來源
透過 Team Foundation Proxy 取得來源

取得未下載某些檔案的來源

您可能會在 tf get 命令的記錄檔中看到「所有檔案最新」的訊息。確認內建服務識別具有下載原始檔案的許可權。識別代號 專案集合建置服務 或 專案建置服務 需要有下載來源的許可權，這取決於在組建管線的 [一般] 索引標籤上選擇的授權範圍。在版本控制 Web UI 中，您可以在資料夾階層的任何層級瀏覽專案檔案，並檢查安全性設定。

透過 Team Foundation Proxy 取得來源

透過 Team Foundation Proxy 設定代理程式以取得來源的最簡單方式是設定環境變數 TFSPROXY ，以指向代理程式以使用者身分執行的 TFVC Proxy 伺服器。

Windows：

    set TFSPROXY=http://tfvcproxy:8081
    setx TFSPROXY=http://tfvcproxy:8081 // If the agent service is running as NETWORKSERVICE or any service account you can't easily set user level environment variable

macOS/Linux：

    export TFSPROXY=http://tfvcproxy:8081

我的流程在命令列步驟上失敗，例如 MSBUILD

釐清建置或發行失敗是否由 Azure Pipelines 產品問題（如代理或任務）所引起會很有幫助。建置和發行失敗也可能來自外部命令。

檢查失敗工作所執行之確切命令行的記錄。嘗試從命令行本機執行命令可能會重現問題。從您的電腦在本機執行命令，和/或登入系統後以服務帳戶身分執行命令，這樣會很有幫助。

例如，問題是在你的建置流程中 MSBuild 階段發生嗎（例如，你是用 MSBuild還是 Visual Studio Build 任務）？如果是，請嘗試使用相同的自變數在本機計算機上執行相同的 MSBuild 命令。如果您可以在本地機器上重現問題，接下來的步驟是調查 MSBuild 問題。

檔案配置

在裝載的代理程式上，建置所需的工具、連結庫、標頭和其他專案的位置，可能會與本機計算機不同。如果組建因為找不到其中一個檔案而失敗，您可以使用下列腳本來檢查代理程式上的配置。這可能有助於追蹤遺漏的檔案。

在暫存位置建立新的 YAML 管線（例如，為了進行疑難解答而建立的新存放庫）。如所撰寫，腳本會在路徑上搜尋目錄。您可以選擇性地編輯該 SEARCH_PATH= 行來搜尋其他地方。

# Script for Linux and macOS
pool: { vmImage: ubuntu-latest } # or whatever pool you use
steps:
- checkout: none
- bash: |
    SEARCH_PATH=$PATH  # or any colon-delimited list of paths
    IFS=':' read -r -a PathDirs <<< "$SEARCH_PATH"
    echo "##[debug] Found directories"
    for element in "${PathDirs[@]}"; do
        echo "$element"
    done;
    echo;
    echo;  
    echo "##[debug] Found files"
    for element in "${PathDirs[@]}"; do
        find "$element" -type f
    done

# Script for Windows
pool: { vmImage: windows-2019 } # or whatever pool you use
steps:
- checkout: none
- powershell: |
    $SEARCH_PATH=$Env:Path
    Write-Host "##[debug] Found directories"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Write-Host "$Dir"
    }
    Write-Host ""
    Write-Host ""
    Write-Host "##[debug] Found files"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Get-ChildItem $Dir -File -ErrorAction Continue | ForEach-Object -Process {
        Write-Host $_.FullName
      }
    }

本機命令提示字元和代理程式之間的差異

請記住，在本機執行命令與在代理上運行建置或發佈時，某些差異會產生影響。如果代理程式設定為在 Linux、macOS 或 Windows 上作為服務執行，那麼它就不會在互動式登入會話中執行。如果沒有互動式登入會話，UI 互動和其他限制就存在。

使用中的檔案或資料夾錯誤

File or folder in use 錯誤會以錯誤訊息表示，例如：

Access to the path [...] is denied.
The process cannot access the file [...] because it is being used by another process.
Access is denied.
Can't move [...] to [...]

疑難排解步驟：

偵測使用中的檔案和資料夾
防毒排除
MSBuild 和 /nodeReuse：false
MSBuild 和 /maxcpucount：[n]

偵測使用中的檔案和資料夾

在Windows上，像 Process Monitor 這類工具可以用來擷取特定目錄下的檔案事件痕跡。或者，針對特定時間點的快照，可以使用 Process Explorer 或 Handle 等工具。

防毒排除

防毒軟體掃描你的檔案可能會在建置或發佈時造成檔案或資料夾使用中錯誤，且建置完成時間可能更長。為您的自架代理程式目錄和流程新增防毒排除功能，有助於解決這些問題。

警告

將檔案或程序排除在防毒掃描之外，可能會讓您的裝置或資料更易受攻擊。評估風險，只排除你確信安全的路徑。

要排除的進程：

Agent.Listener.exe
Agent.Worker.exe
AgentService.exe

代理安裝目錄（例如， C:\agent 或 /home/user/myagent）
代理人工作資料夾： <agent_directory>\_work
代理診斷資料夾： <agent_directory>\_diag
建立為管線設定的輸出資料夾，例如暫存目錄、工件投放位置和符號發佈路徑
%ProgramFiles%\Microsoft Visual Studio\<VersionNumber> （Windows）
C:\Windows\Microsoft.NET\Framework\<VersionNumber>\Temporary ASP.NET Files （Windows）
C:\Windows\Microsoft.NET\Framework64\<VersionNumber>\Temporary ASP.NET Files （Windows）

欲了解更多資訊，請參閱防毒掃描排除條款。

MSBuild 和 /nodeReuse：false

如果您在建置期間叫用 MSBuild，請務必傳遞自變數 /nodeReuse:false （簡短格式 /nr:false）。否則，MSBuild 進程會在組建完成之後繼續執行。流程將持續運行一段時間，以等待可能的後續建置。

MSBuild 的這項功能可能會干擾嘗試刪除或移動目錄，因為與 MSBuild 的進程的工作目錄發生衝突。

MSBuild 和 Visual Studio Build 任務已經在傳給 MSBuild 的參數中加上 /nr:false。不過，如果您從自己的腳本叫用 MSBuild，則必須指定自變數。

MSBuild 和 /maxcpucount：[n]

預設情況下，建置任務如 MSBuild 和 Visual Studio Build會搭配 /m 交換器執行 MSBuild。在某些情況下，這可能會導致多個進程檔案存取問題等問題。

請嘗試將 /m:1 自變數新增至建置工作，以強制 MSBuild 一次只執行一個進程。

利用 MSBuild 的並行進程功能時，可能會產生檔案使用中的問題。未指定自變數 /maxcpucount:[n] （簡短格式 /m:[n]）會指示 MSBuild 只使用單一進程。如果你使用 MSBuild 或 Visual Studio 的 Build 任務，可能需要指定「/m：1」來覆蓋預設新增的「/m」參數。

間歇性或不一致的 MSBuild 失敗

如果您遇到間歇性或不一致的 MSBuild 失敗，請嘗試指示 MSBuild 僅使用單一進程。間歇性或不一致的錯誤可能表示您的目標組態與 MSBuild 的並行進程功能不相容。請參閱 MSBuild 和 /maxcpucount：[n]。

處理序停止回應

進程會停止回應原因和疑難解答步驟：

等候輸入
程序轉儲
WiX 專案

等候輸入

停止回應的進程可能表示進程正在等候輸入。

從互動式登入會話的命令行執行代理程式，可能有助於識別進程是否提示輸入對話方塊。

將代理程式設為服務執行，可能有助於避免程式要求輸入。例如在 .NET 中，程式可能依賴 System.Environment.UserInteractive 布林值來判斷是否要提示。當代理以 Windows 服務形式執行時，該值為 false。

程序轉儲

分析進程的傾印有助於識別死結進程正在等候的內容。

WiX 專案

在啟用自定義 MSBuild 記錄器時建置 WiX 專案，可能會導致 WiX 處於死結狀態，等候輸出資料流。新增額外的 MSBuild 自變數 /p:RunWixToolsOutOfProc=true 適用於此問題。

多個平台的行尾結束符號

當您在多個平台上運行流水線時，有時可能會遇到由於行尾不同而產生的問題。歷史上，Linux 和 macOS 使用「換行」（LF）字元，而 Windows 則使用「回車」加上「換行」（CRLF）。 Git 嘗試補償差異，自動將存儲庫裡的行尾字元設為 LF，但在 Windows 的工作目錄裡則使用 CRLF。

大多數 Windows 工具對僅有 LF 結尾都沒問題，這種自動行為可能帶來更多問題而非解決。如果您遇到與行結尾相關的問題，我們建議您將 Git 設定為偏好使用 LF 作為預設。若要這樣做，請將檔案新增 .gitattributes 至存放庫的根目錄。在該檔案中，新增下列這一行：

* text eol=lf

附加 ' （單引號）的變數

如果您的管線包含使用 ##vso 命令設定變數的 Bash 腳本，您可能會看到另一個 ' 附加至您所設定變數的值。這是因為與 set -x 發生互動。解決方案是在設定變數之前暫時停用 set -x。執行該作業的 Bash 語法為 set +x。

set +x
echo ##vso[task.setvariable variable=MY_VAR]my_value
set -x

為何發生此狀況？

許多 Bash 腳稿都包含 set -x 命令來協助偵錯。 Bash 會追蹤執行命令的確切內容，並將其回應至 stdout。這會導致代理程式看到 ##vso 命令兩次，而第二次，Bash 會將字元新增 ' 至結尾。

例如，請考慮此管線：

steps:
- bash: |
    set -x
    echo ##vso[task.setvariable variable=MY_VAR]my_value

在 stdout 上，代理程式會看到兩行：

##vso[task.setvariable variable=MY_VAR]my_value
+ echo '##vso[task.setvariable variable=MY_VAR]my_value'

當代理程式看到第一行時， MY_VAR 將會設定為正確的值「my_value」。。不過，當它看到第二行時，代理程式會將所有項目處理到該行結尾。 MY_VAR 設定為 "my_value'"。

執行腳本時Python應用程式不會安裝函式庫

當Python應用程式部署時，有時會執行 CI/CD 管線並成功部署程式碼，但負責安裝所有相依函式庫的 requirements.txt 檔案無法執行。

若要安裝相依性，請在App Service 部署工作中使用部署後腳本。下列範例顯示您必須在部署後腳本中使用的命令。您可以更新案例的腳本。

D:\home\python364x64\python.exe -m pip install -r requirements.txt

若要針對與服務連線相關的問題進行疑難解答，請參閱服務連線疑難解答。若要專門針對使用工作負載身分識別進行驗證的服務連線進行故障排除，請參閱工作負載身分識別服務連線故障排除。

管線停止接收到來自代理的訊息

如果您的管線失敗並出現類似的 We stopped hearing from agent <agent name>. Verify the agent machine is running and has a healthy network connection.訊息，請檢查代理程式的資源使用率，以查看代理程式機器是否用盡資源。從 Sprint 228 開始，Azure Pipelines 日誌包含每個步驟的資源利用指標。

使用 Azure DevOps 服務時，你可以透過啟用 verbose logs，在日誌中看到資源使用情況，包括磁碟使用率、記憶體使用率及 CPU 利用率。當管線完成時，搜尋日誌找出每個步驟的 Agent environment resources 條目。

2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23%

如需擷取其他資源使用率記錄的資訊，請參閱擷取資源使用率詳細數據。

啟用 Storage Explorer 透過 Azure Pipelines 將來自 Azure DevOps 的靜態內容（如 .css 和 .js）部署到靜態網站

在這種情況下，你可以使用 Azure 檔案複製任務將內容上傳到網站。您可以使用上傳內容以將內容上傳至 Web 容器中所述的任何工具。

後續步驟

檢閱記錄以找出其他診斷工具。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-11