共用方式為

流程執行的疑難排解

  • 發行項

Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019

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

管線執行摘要頁面的螢幕快照，其中包含診斷資訊。

檢視記錄

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

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

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

管線執行診斷日誌的截圖。

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

Azure DevOps 中記錄檢視選項的螢幕快照。

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

錯誤分析頁面

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

管線執行摘要頁面上檢視分析圖示的螢幕快照。

Azure DevOps Server 檢視分析圖示的螢幕快照。

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

Azure DevOps 入口網站中錯誤分析頁面的螢幕快照。

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

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

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

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

常見問題

失敗管線運行的任務分析

Azure DevOps 提供 [ 失敗管線執行的工作深入解析 ] 設定，當啟用時，會提供建置失敗的快顯通知，並提供檢視報告的連結。

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

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

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

失敗執行的通知

Azure DevOps 包含失敗管線執行的內建通知。 若要啟用通知：

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

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

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

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

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

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

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

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

授權特定管線

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

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

  1. 在 Azure DevOps 中，移至 [項目設定]、 [代理程式集區]、選擇您的自我裝載集區，然後選擇 [ 安全性]。
  2. 選擇 + 將管線新增至授權清單。
  3. 選擇 [X（撤銷存取權] 以從授權清單中移除管線。

設定開啟存取

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

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

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

  1. 在 Azure DevOps 中，移至 [項目設定]、 [代理程式集區]、選擇您的自我裝載集區，然後選擇 [ 安全性]。
  2. 選擇 [其他動作]、[ 開啟存取權] 以啟用開啟存取權，然後選擇 [再次 開啟存取 ] 以確認。
  3. 若要撤銷開啟存取權，請選擇 [ 限制許可權]。

若要檢閱 開放存取 是否適用於其他 資源類型，請參閱 管理 Azure Pipelines 中的安全性 ，並搜尋 Open access。

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

作業逾時

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

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

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

深入了解作業 逾時。

備註

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

下載程式代碼時發生問題

我的流水線在檢出步驟時失敗

如果您在 checkout 組織中與管線不同的專案中使用 Azure Repos Git 存放庫的步驟，請確定已停用 將作業授權範圍限制為目前的項目 設定，或遵循 限定範圍的組建身 分識別中的步驟，以確保您的管線可以存取存放庫。

當管線因為作業授權範圍有限而無法存取儲存庫時，您會收到錯誤 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） 問題

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

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

透過 Team Foundation Proxy 取得來源

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

窗戶：

    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 [...]

疑難排解步驟：

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

在 Windows 上， 行程監視器 之類的工具可以擷取特定目錄下的檔案事件的追蹤。 或者，針對特定時間點的快照，可以使用 Process Explorer 或 Handle 等工具。

防毒排除

掃描檔案的防病毒軟體可能會導致建置或發行期間發生檔案或資料夾使用錯誤。 為您的代理程式目錄新增防毒排除，並設定 「工作資料夾」有助於將防病毒軟體識別為干擾程式。

MSBuild 和 /nodeReuse：false

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

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

MSBuild 和 Visual Studio 建置工作已新增 /nr:false 至傳遞至 MSBuild 的自變數。 不過，如果您從自己的腳本叫用 MSBuild，則必須指定 自變數。

MSBuild 和 /maxcpucount：[n]

根據預設， MSBuild 和 Visual Studio Build 等建置工作會使用 /m 參數執行 MSBuild。 在某些情況下，這可能會導致多個進程檔案存取問題等問題。

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

利用 MSBuild 的並行進程功能時，可能會產生檔案使用中的問題。 未指定自變數 /maxcpucount:[n] （簡短格式 /m:[n]）會指示 MSBuild 只使用單一進程。 如果您使用 MSBuild 或 Visual Studio 建置工作，您可能需要指定 “/m：1” 來覆寫預設新增的 “/m” 自變數。

間歇性或不一致的 MSBuild 失敗

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

進程停止回應

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

等候輸入

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

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

將代理程式設為服務執行，可能有助於避免程式要求輸入。 例如，在 .NET 中，程式可能會依賴 System.Environment.UserInteractive Boolean 來判斷是否要提示。 當代理程式以 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 Services 時，您可以在記錄中看到資源使用率，包括磁碟使用量、記憶體使用量和 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%

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

啟用儲存體總管，透過 Azure Pipelines 從 Azure DevOps 將靜態內容（如 .css 和 .js）部署至靜態網站。

在此案例中，您可以使用 Azure 檔案複製工作 將內容上傳至網站。 您可以使用 上傳內容 以將內容上傳至 Web 容器中所述的任何工具。

後續步驟