自定義適用於 Azure Pipelines 的 JavaScript
您可以使用 Azure Pipelines 來建置 JavaScript 應用程式,而不需要設定您自己的任何基礎結構。 您常用來建置、測試及執行 JavaScript 應用程式的工具,例如 npm、Node、Yarn 和 Gulp ,會在 Azure Pipelines 中的Microsoft裝載代理程式上預安裝。
如需預安裝的 Node.js 和 npm 版本,請參閱 Microsoft裝載的代理程式。 若要在裝載Microsoft代理程式上安裝特定版本的這些工具,請將 Node Tool Installer 工作新增至程式的開頭。 您也可以使用 自我裝載 的代理程式。
若要使用 JavaScript 建立您的第一個管線,請參閱 JavaScript 快速入門。
使用特定版本的 Node.js
如果您需要Microsoft裝載的代理程式上尚未安裝的 Node.js 和 npm 版本,請使用 Node 工具安裝程式工作。 將下列代碼段新增至您的 azure-pipelines.yml
檔案。
注意
裝載的代理程式會定期更新,而且設定此工作會導致每次執行管線時,花費大量時間更新為較新的次要版本。 只有在管線中需要特定節點版本時,才使用此工作。
- task: UseNode@1
inputs:
version: '16.x' # replace this value with the version that you need for your project
如果您需要尚未安裝在代理程式上的 Node.js/npm 版本:
在管線中,選取 [工作],選擇執行建置工作的階段,然後選取 + 將新工作新增至該階段。
在工作目錄中,尋找並新增 Node Tool Installer 工作。
選取工作,並指定您要安裝的Node.js運行時間版本。
若要只更新 npm 工具,請在建置程式中執行 npm i -g npm@version-number
命令。
使用多個節點版本
您可以使用 Node 工具安裝程式工作,在多個版本的 Node 上建置及測試您的應用程式。
pool:
vmImage: 'ubuntu-latest'
strategy:
matrix:
node_16_x:
node_version: 16.x
node_13_x:
node_version: 18.x
steps:
- task: UseNode@1
inputs:
version: $(node_version)
- script: npm install
請參閱 多重設定執行。
在組建代理程式上安裝工具
如果您的專案 package.json
或 package-lock.json
檔案中有開發相依性的工具,請透過 npm 安裝工具和相依性。 工具的確切版本會在項目中定義,與建置代理程式上存在的其他版本隔離。
使用腳本搭配package.json安裝
- script: npm install --only=dev
使用 npm 工作搭配 package.json 安裝
- task: Npm@1
inputs:
command: 'install'
使用 npm npx
套件執行器以這種方式安裝工具,以偵測路徑解析中以這種方式安裝的工具。 下列範例會呼叫 mocha
測試執行器,但在使用全域安裝(到 npm install -g
) 版本之前,先尋找安裝為開發相依性的版本。
- script: npx mocha
若要安裝專案所需的工具,但未在 中 package.json
設定為開發相依性,請從管線中的腳本階段呼叫 npm install -g
。
下列範例會使用 npm
安裝最新版的 Angular CLI。 接著 ng
,管線的其餘部分可以使用其他 script
階段的工具。
注意
在Microsoft裝載的 Linux 代理程式上,使用 sudo
前置命令,例如 sudo npm install -g
。
- script: npm install -g @angular/cli
提示
這些工作會在每次管線執行時執行,因此請注意安裝工具對建置時間的影響。 如果額外負荷對您的組建效能造成嚴重影響,請考慮使用所需的工具版本來設定 自我裝載代理程式 。
使用管線中的 npm 或命令行工作,在組建代理程式上安裝工具。
管理相依性
在您的組建中,使用 Yarn 或 Azure Artifacts 從公用 npm 登錄下載套件。 此登錄是您在檔案中指定的 .npmrc
私人 npm 登錄類型。
使用 npm
您可以使用下列方式使用 npm 來下載組建的套件:
- 直接在管線中執行
npm install
,因為它是從登錄下載套件的最簡單方式,而不需要驗證。 如果您的組建不需要在代理程式上執行開發相依性,您可以使用 選項npm install
來加速建置時間--only=prod
。 - 使用 npm 工作。 當您使用已驗證的登錄時,此工作很有用。
- 使用 npm 驗證工作。 當您從工作執行器內執行
npm install
時,此工作很有用 - Gulp、Grunt 或 Maven。
如果您想要指定 npm 登錄,請將URL放在存放庫中的檔案中 .npmrc
。
如果您的摘要經過驗證,請在 [項目設定] 中的 [服務] 索引卷標上建立 npm 服務連線,以管理其認證。
若要在管線中使用文稿安裝 npm 套件,請將下列代碼段新增至 azure-pipelines.yml
。
- script: npm install
若要使用檔案 .npmrc
中指定的私人登錄,請將下列代碼段新增至 azure-pipelines.yml
。
- task: Npm@1
inputs:
customEndpoint: <Name of npm service connection>
若要透過 Gulp 之類的工作執行器將登入認證傳遞至 npm 命令,請在呼叫工作執行器之前,將下列工作新增至 azure-pipelines.yml
。
- task: npmAuthenticate@0
inputs:
customEndpoint: <Name of npm service connection>
使用管線中的 npm 或 npm 驗證工作來下載及安裝套件。
如果您的組建偶爾因為從 npm 登錄還原套件時發生連線問題而失敗,您可以使用 Azure Artifacts 搭配 上游來源,並快取套件。 當您連線到 Azure Artifacts 時,會自動使用管線的認證。 這些認證通常衍生自 Project Collection Build Service 帳戶。
如果您使用 Microsoft裝載的代理程式,則每次執行組建時都會取得新計算機,這表示每次還原相依性,這可能需要大量的時間。 若要減輕問題,您可以使用 Azure Artifacts 或自我裝載的代理程式,然後取得使用套件快取的優點。
使用 Yarn
使用腳本階段叫用 Yarn 來還原相依性。 Yarn 會預安裝於某些 Microsoft裝載的代理程式上。 您可以像任何其他工具一樣,在自我裝載的代理程式上安裝及設定它。
- script: yarn install
使用管線中的 CLI 或 Bash 工作來叫用 Yarn。
執行 JavaScript 編譯程式
使用 Babel 和 TypeScript tsc
編譯程式之類的編譯程式,將原始程式碼轉換成可供Node.js運行時間或網頁瀏覽器中使用的版本。
如果您在執行編譯程式的項目package.json
檔中設定了腳本物件,請使用腳本工作在管線中叫用它。
- script: npm run compile
您可以使用文稿工作直接從管線呼叫編譯程式。 這些命令會從複製之原始程式碼存放庫的根目錄執行。
- script: tsc --target ES6 --strict true --project tsconfigs/production.json
如果您的專案中已定義編譯腳本,請使用管線中的 npm 工作package.json來建置程式代碼。 如果您沒有在專案組態中定義個別的腳本,請使用Bash工作來編譯程式代碼。
執行單元測試
設定管線以執行 JavaScript 測試,使其產生以 JUnit XML 格式格式化的結果。 接著,您可以使用內 建的發佈測試結果工作來發佈結果 。
如果您的測試架構不支援 JUnit 輸出,請透過合作夥伴報告模組新增支援,例如 mocha-junit-reporter。 您可以更新測試文本以使用 JUnit 記者,或如果記者支援命令行選項,請將這些選項傳遞至工作定義。
下表列出最常使用的測試執行器和可用於產生 XML 結果的記者:
測試執行器 | 記者產生 XML 報告 |
---|---|
mocha | 莫查-朱尼特-記者 賽普拉斯-多記者 |
茉莉花 | 茉莉花-記者 |
jest | jest-junit jest-junit-reporter |
業 | karma-junit-reporter |
Ava | tap-xunit |
下列範例會使用 mocha-junit-reporter ,並使用腳本直接叫 mocha test
用 。 此文稿會在的預設位置 ./test-results.xml
產生 JUnit XML 輸出。
- script: mocha test --reporter mocha-junit-reporter
如果您在專案package.json檔案中定義 test
腳本,您可以使用 來叫用 npm test
它。
- script: npm test
發佈測試結果
若要發佈結果,請使用 [發佈測試結果] 工作。
- task: PublishTestResults@2
condition: succeededOrFailed()
inputs:
testRunner: JUnit
testResultsFiles: '**/test-results.xml'
發佈程式代碼涵蓋範圍結果
如果您的測試腳本執行程式代碼涵蓋範圍工具,例如 伊斯坦布爾,請新增 [發佈程式代碼涵蓋範圍結果] 工作 。 當您這樣做時,您可以在組建摘要中找到涵蓋範圍計量,並下載 HTML 報告以進行進一步分析。 工作需要 Cobertura 或 JaCoCo 報告輸出,因此請確定您的程式代碼涵蓋範圍工具會以必要的選項執行,以產生正確的輸出。 例如: --report cobertura
。
下列範例會使用 nyc、伊斯坦布爾命令行介面,以及 mocha-junit-reporter 和 invokes npm test
命令。
- script: |
nyc --reporter=cobertura --reporter=html \
npm test -- --reporter mocha-junit-reporter --reporter-options mochaFile=./test-results.xml
displayName: 'Build code coverage report'
- task: PublishCodeCoverageResults@2
inputs:
summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'
使用管線中的 [發佈測試結果] 和 [發佈程式代碼涵蓋範圍結果] 工作,使用伊斯坦布爾發佈測試結果以及程式代碼涵蓋範圍結果。
將 [發佈測試結果] 工作的 [控制選項] 設定為執行工作,即使先前的工作失敗,除非取消部署。
測試瀏覽器端對端
使用 Protractor 或 Karma 等工具,在無頭瀏覽器中執行測試。 然後使用下列步驟將組建的結果發佈至 Azure DevOps:
- 在組建代理程式上安裝無頭瀏覽器測試驅動程式,例如無頭 Chrome 或 Firefox,或瀏覽器模擬工具,例如 PhantomJS。
- 根據工具的檔,將您的測試架構設定為使用您選擇的無頭部瀏覽器/驅動程序選項。
- 設定您的測試架構(通常是使用記者外掛程式或元件或元件),以輸出 JUnit 格式的測試結果。
- 設定文稿工作以執行啟動無外設瀏覽器實例所需的任何 CLI 命令。
- 在管線階段以及單元測試中執行端對端測試。
- 使用與單元測試相同的 [發佈測試結果] 工作來發佈結果。
封裝 Web 應用程式
封裝應用程式,將所有應用程式模組與中繼輸出和相依性組合在準備好進行部署的靜態資產中。 在編譯和測試之後新增管線階段,以使用 Angular CLI 執行 Webpack 或 ng 組建之類的工具。
第一個範例會呼叫 webpack
。 若要進行這項工作,請確定已 webpack
設定為package.json項目檔中的開發相依性。 webpack
除非您在專案的根資料夾中有檔案webpack.config.js
,否則這會使用預設組態執行。
- script: webpack
下一個範例會使用 npm 工作呼叫 ,以呼叫build
npm run build
項目中定義的腳本物件package.json。 在您的專案中使用腳本物件,會將組建的邏輯移至原始程式碼和管線外。
- script: npm run build
使用管線中的 CLI 或 Bash 工作來叫用封裝工具,例如 webpack
或 Angular 的 ng build
。
實作 JavaScript 架構
Angular
針對 Angular 應用程式,您可以包含 Angular 特定命令,例如 ng 測試、 ng 組建和 ng e2e。 若要在管線中使用 Angular CLI 命令,請在 組建代理程式上安裝 angular/cli npm 套件 。
注意
在Microsoft裝載的 Linux 代理程式上,使用 sudo
前置命令,例如 sudo npm install -g
。
- script: |
npm install -g @angular/cli
npm install
ng build --prod
將下列工作新增至管線:
npm \(英文\)
- 命令:
custom
- 命令和自變數:
install -g @angular/cli
- 命令:
npm \(英文\)
- 命令:
install
- 命令:
bash
- 類型:
inline
- 腳本:
ng build --prod
- 類型:
針對管線中需要瀏覽器執行的測試,例如 執行 Karma 之入門應用程式中的 ng 測試 命令,請使用無頭瀏覽器,而不是標準瀏覽器。 在 Angular 入門應用程式中:
將
browsers
karma.conf.js項目檔中的項目從browsers: ['Chrome']
變更為browsers: ['ChromeHeadless']
。將
singleRun
karma.conf.js項目檔中的項目從的值false
變更為true
。 這項變更有助於確保 Karma 進程在執行之後停止。
React 和 Vue
React 和 Vue 應用程式的所有相依性都會擷取在package.json檔案中。 您的 azure-pipelines.yml 檔案包含標準Node.js腳本:
- script: |
npm install
displayName: 'npm install'
- script: |
npm run build
displayName: 'npm build'
組建檔案位於新資料夾中( dist
適用於 Vue) 或 build
(適用於 React)。 此代碼段會建置成品 - www
已準備好發行。 它會使用 Node Installer、 Copy Files 和 Publish Build Artifacts 工作 。
trigger:
- main
pool:
vmImage: 'ubuntu-latest'
steps:
- task: UseNode@1
inputs:
version: '16.x'
displayName: 'Install Node.js'
- script: |
npm install
displayName: 'npm install'
- script: |
npm run build
displayName: 'npm build'
- task: CopyFiles@2
inputs:
Contents: 'build/**' # Pull the build directory (React)
TargetFolder: '$(Build.ArtifactStagingDirectory)'
- task: PublishBuildArtifacts@1
inputs:
PathtoPublish: $(Build.ArtifactStagingDirectory) # dist or build files
ArtifactName: 'www' # output artifact named www
若要發行,請將您的發行工作指向 dist
或 build
成品,並使用 Azure Web 應用程式部署工作。
Webpack
您可以使用 Webpack 組態檔來指定編譯程式,例如 Babel 或 TypeScript,將 JSX 或 TypeScript 轉譯為一般 JavaScript,以及將您的應用程式組合在一起。
- script: |
npm install webpack webpack-cli --save-dev
npx webpack --config webpack.config.js
將下列工作新增至管線:
npm \(英文\)
- 命令:
custom
- 命令和自變數:
install -g webpack webpack-cli --save-dev
- 命令:
bash
- 類型:
inline
- 腳本:
npx webpack --config webpack.config.js
- 類型:
建置工作執行器
通常使用 Gulp 或 Grunt 作為工作執行器來建置及測試 JavaScript 應用程式。
Gulp
Gulp 會預安裝在Microsoft裝載的代理程式上。 gulp
在 YAML 檔案中執行 命令:
- script: gulp # include any additional options that are needed
如果您的gulpfile.js檔案中的步驟需要使用 npm 登錄進行驗證:
- task: npmAuthenticate@0
inputs:
customEndpoint: <Name of npm service connection>
- script: gulp # include any additional options that are needed
新增 [ 發佈測試結果] 工作,將 JUnit 或 xUnit 測試結果發佈至伺服器。
- task: PublishTestResults@2
inputs:
testResultsFiles: '**/TEST-RESULTS.xml'
testRunTitle: 'Test results for JavaScript using gulp'
新增 [ 發佈程式代碼涵蓋範圍結果] 工作,將程式代碼涵蓋範圍結果發佈至伺服器。 您可以在組建摘要中找到涵蓋範圍計量,也可以下載 HTML 報表以進行進一步分析。
- task: PublishCodeCoverageResults@1
inputs:
codeCoverageTool: Cobertura
summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'
reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage'
如果您的應用程式使用 Gulp 來建立管線,最簡單的方式是當您建立管線時,使用 Node.js 搭配 gulp 建置範本。 此範本會自動新增各種工作來叫用 Gulp 命令,以及發佈成品。 在工作中,選取 [ 啟用程式代碼涵蓋範圍 ] 以使用伊斯坦布爾啟用程式代碼涵蓋範圍。
Grunt
Grunt 會在Microsoft裝載的代理程式上預安裝。 若要在 YAML 檔案中執行 grunt 命令:
- script: grunt # include any additional options that are needed
如果您的檔案中的 Gruntfile.js
步驟需要使用 npm 登錄進行驗證:
- task: npmAuthenticate@0
inputs:
customEndpoint: <Name of npm service connection>
- script: grunt # include any additional options that are needed
如果您的應用程式使用 Grunt,則建立管線最簡單的方式是當您建立管線時,使用 Node.js 搭配 Grunt 建置範本。 這會自動新增各種工作來叫用 Gulp 命令和發佈成品。 在工作中,選取 [ 發佈至 TFS/Team Services ] 選項以發佈測試結果,然後選取 [ 啟用程式代碼涵蓋範圍 ] 以使用伊斯坦布爾啟用程式代碼涵蓋範圍。
封裝並傳遞您的程序代碼
建置並測試應用程式之後,您可以將組建輸出上傳至 Azure Pipelines、建立和發佈 npm 或 Maven 套件,或將組建輸出封裝到.zip檔案中,以部署至 Web 應用程式。
將檔案發佈至 Azure Pipelines
若要上傳整個工作目錄的檔案,請使用 [發佈組建成品 ] 工作,並將下列內容新增至您的 azure-pipelines.yml
檔案。
- task: PublishBuildArtifacts@1
inputs:
PathtoPublish: '$(System.DefaultWorkingDirectory)'
若要上傳檔案的子集,請先從工作目錄將必要的檔案複製到具有 複製檔案 工作的預備目錄,然後使用 [發佈組建成品] 工作。
- task: CopyFiles@2
inputs:
SourceFolder: '$(System.DefaultWorkingDirectory)'
Contents: |
**\*.js
package.json
TargetFolder: '$(Build.ArtifactStagingDirectory)'
- task: PublishBuildArtifacts@1
將模組發佈至 npm 登錄
如果您的項目的輸出是 npm
其他專案而非 Web 應用程式的模組,請使用 npm 工作將模組發佈至本機登錄或公用 npm 登錄。 每次發佈時,請提供唯一的名稱/版本組合。
範例
第一個範例假設您透過版本控制中的檔案變更package.json
來管理版本資訊(例如透過 npm 版本)。 下列範例會使用腳本工作發佈至公用登錄。
- script: npm publish
下一個範例會發佈至存放庫 .npmrc
檔案中定義的自定義登錄。 設定 npm 服務連線 ,以在組建執行時將驗證認證插入連線。
- task: Npm@1
inputs:
command: publish
publishRegistry: useExternalRegistry
publishEndpoint: https://my.npmregistry.com
最後一個範例會將模組發佈至 Azure DevOps Services 套件管理摘要。
- task: Npm@1
inputs:
command: publish
publishRegistry: useFeed
publishFeed: https://my.npmregistry.com
如需版本設定和發佈 npm 套件的詳細資訊,請參閱發佈 npm 套件,以及如何將 npm 套件版本設定為建置程式的一部分?。
部署 Web 應用程式
若要建立可供發佈至 Web 應用程式的.zip檔案封存,請使用封 存盤 工作:
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: '$(System.DefaultWorkingDirectory)'
includeRootFolder: false
若要將此封存發佈至 Web 應用程式,請參閱 Azure Web 應用程式部署。
將成品發佈至 Azure Pipelines
使用 [ 發佈組建成品] 工作 ,將檔案從組建發佈至 Azure Pipelines。
發佈至 npm 登錄
若要建立及發佈 npm 套件,請使用 npm 工作。 如需版本設定和發佈 npm 套件的詳細資訊,請參閱 發佈 npm 套件。
部署 Web 應用程式
若要建立可供發佈至 Web 應用程式的.zip檔案封存,請使用封 存盤工作。 若要將此封存發佈至 Web 應用程式,請參閱 Azure Web 應用程式部署。
疑難排解
如果您在開發計算機上建置專案,但無法在 Azure Pipelines 上建置專案,請探索下列可能的原因和修正動作:
檢查開發電腦上的Node.js版本和工作執行器是否符合代理程式上的版本。 您可以在管線中包含命令行腳本
node --version
,以檢查代理程式上安裝的內容。 使用 Node Tool Installer (如本指南所述)在代理程式上部署相同版本,或執行npm install
命令,將工具更新為想要的版本。如果您的組建在還原套件時間歇性失敗,則 npm 登錄有問題,或 Azure 數據中心與登錄之間發生網路問題。 我們無法控制這些因素。 探索是否將 Azure Artifacts 與 npm 登錄搭配使用,作為上游來源可改善組建的可靠性。
如果您使用
nvm
來管理不同版本的Node.js,請考慮改為切換至 Node Tool Installer 工作。 (nvm
基於 macOS 映射的歷史原因而安裝。nvm
藉由新增殼層別名和改變PATH
來管理多個Node.js版本,這與 Azure Pipelines 在新進程中執行每個工作的方式互動不佳。Node Tool Installer 工作會正確處理此模型。 不過,如果您的工作需要使用
nvm
,您可以將下列腳本新增至每個管線的開頭:steps: - bash: | NODE_VERSION=16 # or whatever your preferred version is npm config delete prefix # avoid a warning . ${NVM_DIR}/nvm.sh nvm use ${NODE_VERSION} nvm alias default ${NODE_VERSION} VERSION_PATH="$(nvm_version_path ${NODE_VERSION})" echo "##vso[task.prependPath]$VERSION_PATH"
然後,
node
和其他命令行工具適用於管線作業的其餘部分。 在您使用 命令的每個步驟nvm
中,使用下列程式代碼啟動文稿:- bash: | . ${NVM_DIR}/nvm.sh nvm <command>
常見問題集
問:我可以在哪裡深入瞭解 Azure Artifacts 和套件管理服務?
問:我可以在哪裡深入瞭解工作?
答: 建置、發行和測試工作
問:如何? 修正管線失敗,並出現「嚴重錯誤:CALL_AND_RETRY_LAST配置失敗 - 記憶體不足的 JavaScript 堆積」訊息?
答:當Node.js套件超過記憶體使用量限制時,就會發生此失敗類型。 若要解決此問題,請新增類似 的 NODE_OPTIONS
變數,並將值指派為 --max_old_space_size=16384。
問:如何將 npm 套件版本設定為建置程式的一部分?
答:其中一個選項是使用版本控制與 npm 版本的組合。 在管線執行結束時,您可以使用新版本來更新存放庫。 在此 YAML 中,有 GitHub 存放庫,套件會部署至 npmjs。 如果您的套件版本在 npmjs 和檔案 package.json
上不符,您的組建就會失敗。
variables:
MAP_NPMTOKEN: $(NPMTOKEN) # Mapping secret var
trigger:
- none
pool:
vmImage: 'ubuntu-latest'
steps: # Checking out connected repo
- checkout: self
persistCredentials: true
clean: true
- task: npmAuthenticate@0
inputs:
workingFile: .npmrc
customEndpoint: 'my-npm-connection'
- task: UseNode@1
inputs:
version: '16.x'
displayName: 'Install Node.js'
- script: |
npm install
displayName: 'npm install'
- script: |
npm pack
displayName: 'Package for release'
- bash: | # Grab the package version
v=`node -p "const p = require('./package.json'); p.version;"`
echo "##vso[task.setvariable variable=packageVersion]$v"
- task: CopyFiles@2
inputs:
contents: '*.tgz'
targetFolder: $(Build.ArtifactStagingDirectory)/npm
displayName: 'Copy archives to artifacts staging directory'
- task: CopyFiles@2
inputs:
sourceFolder: '$(Build.SourcesDirectory)'
contents: 'package.json'
targetFolder: $(Build.ArtifactStagingDirectory)/npm
displayName: 'Copy package.json'
- task: PublishBuildArtifacts@1
inputs:
PathtoPublish: '$(Build.ArtifactStagingDirectory)/npm'
artifactName: npm
displayName: 'Publish npm artifact'
- script: | # Config can be set in .npmrc
npm config set //registry.npmjs.org/:_authToken=$(MAP_NPMTOKEN)
npm config set scope "@myscope"
# npm config list
# npm --version
npm version patch --force
npm publish --access public
- task: CmdLine@2 # Push changes to GitHub (substitute your repo)
inputs:
script: |
git config --global user.email "username@contoso.com"
git config --global user.name "Azure Pipeline"
git add package.json
git commit -a -m "Test Commit from Azure DevOps"
git push -u origin HEAD:main