Anpassa JavaScript för Azure Pipelines

Du kan använda Azure Pipelines för att skapa dina JavaScript-appar utan att behöva konfigurera någon egen infrastruktur. Verktyg som du ofta använder för att skapa, testa och köra JavaScript-appar – t.ex. npm, Node, Yarn och Gulp – blir förinstallerade på Microsoft-värdbaserade agenter i Azure Pipelines.

Den version av Node.js och npm som är förinstallerad finns i Microsoft-värdbaserade agenter. Om du vill installera en specifik version av dessa verktyg på Microsoft-värdbaserade agenter lägger du till uppgiften Installationsprogram för nodverktyg i början av processen. Du kan också använda en lokalt installerad agent.

Information om hur du skapar din första pipeline med JavaScript finns i Snabbstart för JavaScript.

Använda en specifik version av Node.js

Om du behöver en version av Node.js och npm som inte redan är installerad på den Microsoft-värdbaserade agenten använder du installationsuppgiften för Node-verktyget. Lägg till följande kodfragment i azure-pipelines.yml filen.

Kommentar

De värdbaserade agenterna uppdateras regelbundet, och om du konfigurerar den här aktiviteten kan du ägna mycket tid åt att uppdatera till en nyare delversion varje gång pipelinen körs. Använd endast den här uppgiften när du behöver en specifik nodversion i pipelinen.

- task: UseNode@1
  inputs:
    version: '16.x' # replace this value with the version that you need for your project

Om du bara vill uppdatera npm-verktyget kör npm i -g npm@version-number du kommandot i byggprocessen.

Använda flera nodversioner

Du kan skapa och testa din app på flera versioner av Node med installationsuppgiften för Node-verktyget.

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

Installera verktyg på byggagenten

Om du har verktyg som är utvecklingsberoenden i projektet package.json eller package-lock.json filen installerar du dina verktyg och beroenden via npm. Den exakta versionen av verktygen definieras i projektet, isolerad från andra versioner som finns i byggagenten.

Använd ett skript eller npm-aktiviteten.

Använd ett skript för att installera med package.json

- script: npm install --only=dev

Använd npm-uppgiften för att installera med package.json

- task: Npm@1
  inputs:
     command: 'install'

Kör verktyg som installerats på det här sättet med hjälp av npm-paketlöparen npx , som identifierar verktyg som är installerade på det här sättet i sin sökvägsupplösning. I följande exempel anropas mocha testlöparen men söker efter den version som installerats som ett utvecklingsberoende innan en globalt installerad (via npm install -g) version används.

- script: npx mocha

Om du vill installera verktyg som projektet behöver men som inte anges som utvecklingsberoenden i package.jsonanropar npm install -g du från ett skriptsteg i pipelinen.

I följande exempel installeras den senaste versionen av Angular CLI med hjälp npmav . Resten av pipelinen kan sedan använda ng verktyget från andra script steg.

Kommentar

På Microsoft-värdbaserade Linux-agenter förordar du kommandot med sudo, till exempel sudo npm install -g.

- script: npm install -g @angular/cli

Dricks

De här uppgifterna körs varje gång pipelinen körs, så tänk på vilken inverkan installationsverktyg har på byggtiderna. Överväg att konfigurera lokalt installerade agenter med den version av verktygen som du behöver om det blir en allvarlig inverkan på byggprestandan.

Hantera beroenden

I din version använder du Yarn eller Azure Artifacts för att ladda ned paket från det offentliga npm-registret. Det här registret är en typ av privat npm-register som du anger i .npmrc filen.

Använd npm

Du kan använda npm på följande sätt för att ladda ned paket för din version:

• Kör npm install direkt i pipelinen eftersom det är det enklaste sättet att ladda ned paket från ett register utan autentisering. Om ditt bygge inte behöver utvecklingsberoenden på agenten för att köras kan du påskynda byggtiden med --only=prod alternativet till npm install.
• Använd en npm-uppgift. Den här uppgiften är användbar när du använder ett autentiserat register.
• Använd en npm Authenticate-uppgift. Den här uppgiften är användbar när du springer npm install inifrån dina aktivitetslöpare – Gulp, Grunt eller Maven.

Om du vill ange ett npm-register placerar du URL:erna i en .npmrc fil på lagringsplatsen. Om ditt flöde autentiseras skapar du en npm-tjänstanslutning på fliken Tjänster i Projektinställningar för att hantera dess autentiseringsuppgifter.

Om du vill installera npm-paket med ett skript i pipelinen lägger du till följande kodfragment i azure-pipelines.yml.

- script: npm install

Om du vill använda ett privat register som anges i .npmrc filen lägger du till följande kodfragment i azure-pipelines.yml.

- task: Npm@1
  inputs:
    customEndpoint: <Name of npm service connection>

Om du vill skicka registerautentiseringsuppgifter till npm-kommandon via aktivitetslöpare som Gulp lägger du till följande aktivitet azure-pipelines.yml innan du anropar aktivitetslöparen.

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

Om dina versioner ibland misslyckas på grund av anslutningsproblem när du återställer paket från npm-registret kan du använda Azure Artifacts med överordnade källor och cachelagrar paketen. Autentiseringsuppgifterna för pipelinen används automatiskt när du ansluter till Azure Artifacts. Dessa autentiseringsuppgifter härleds vanligtvis från Project Collection Build Service-kontot .

Om du använder Microsoft-värdbaserade agenter får du en ny dator varje gång du kör en version, vilket innebär att återställa beroendena varje gång, vilket kan ta lång tid. För att minimera kan du använda Azure Artifacts eller en lokalt installerad agent – sedan får du fördelen av att använda paketcacheminnet.

Använda Yarn

Använd ett skriptsteg för att anropa Yarn för att återställa beroenden. Yarn förinstalleras på vissa Microsoft-värdbaserade agenter. Du kan installera och konfigurera den på lokalt installerade agenter som alla andra verktyg.

- script: yarn install

Köra JavaScript-kompilatorer

Använd kompilatorer som Babel och TypeScript-kompilatorn tsc för att konvertera källkoden till versioner som kan användas av Node.js-körningen eller i webbläsare.

Om du har konfigurerat ett skriptobjekt i projektfilen package.json som kör kompilatorn anropar du det i pipelinen med hjälp av en skriptuppgift.

- script: npm run compile

Du kan anropa kompilatorer direkt från pipelinen med hjälp av skriptuppgiften. Dessa kommandon körs från roten på den klonade källkodslagringsplatsen.

- script: tsc --target ES6 --strict true --project tsconfigs/production.json

Köra enhetstester

Konfigurera dina pipelines så att de kör JavaScript-testerna så att de ger resultat som är formaterade i JUnit XML-format. Du kan sedan publicera resultaten med hjälp av den inbyggda publiceringstestresultataktiviteten .

Om testramverket inte stöder JUnit-utdata lägger du till stöd via en partnerrapporteringsmodul, till exempel mocha-junit-reporter. Du kan antingen uppdatera testskriptet för att använda JUnit-reportern, eller om reportern har stöd för kommandoradsalternativ skickar du dessa alternativ till uppgiftsdefinitionen.

I följande tabell visas de vanligaste testlöparna och de reportrar som kan användas för att skapa XML-resultat:

Testkörare	Reportrar för att skapa XML-rapporter
mocka	mocha-junit-reporter cypress-multi-reportrar
jasmin	jasmine-reportrar
skämta	jest-junit jest-junit-reporter
karma	karma-junit-reporter
Ava	tap-xunit

I följande exempel används mocha-junit-reporter och anropas mocha test direkt med hjälp av ett skript. Det här skriptet genererar JUnit XML-utdata på standardplatsen ./test-results.xmlför .

- script: mocha test --reporter mocha-junit-reporter

Om du har definierat ett test skript i projektet package.json fil kan du anropa det med hjälp npm testav .

- script: npm test

Publicera testresultat

Om du vill publicera resultaten använder du aktiviteten Publicera testresultat .

- task: PublishTestResults@2
  condition: succeededOrFailed()
  inputs:
    testRunner: JUnit
    testResultsFiles: '**/test-results.xml'

Publicera resultat för kodtäckning

Om testskripten kör ett kodtäckningsverktyg, till exempel Istanbul, lägger du till uppgiften Publicera kodtäckningsresultat . När du gör det kan du hitta täckningsmått i byggsammanfattningen och ladda ned HTML-rapporter för ytterligare analys. Uppgiften förväntar sig Cobertura- eller JaCoCo-rapporteringsutdata, så se till att kodtäckningsverktyget körs med de alternativ som krävs för att generera rätt utdata. Exempel: --report cobertura

I följande exempel används nyc, istanbuls kommandoradsgränssnitt, tillsammans med mocha-junit-reporter och anropar npm test kommandot.

- 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'

Testa webbläsaren från slutpunkt till slutpunkt

Kör tester i huvudlösa webbläsare som en del av din pipeline med verktyg som Protractor eller Karma. Publicera sedan resultatet för versionen till Azure DevOps med följande steg:

1. Installera en huvudlös webbläsartestdrivrutin, till exempel headless Chrome eller Firefox, eller ett webbläsarföraktande verktyg som PhantomJS, på byggagenten.
2. Konfigurera ditt testramverk så att det använder valfritt webbläsar-/drivrutinsalternativ enligt verktygets dokumentation.
3. Konfigurera testramverket (vanligtvis med ett plugin-program eller en konfiguration för reporter) för att mata ut JUnit-formaterade testresultat.
4. Konfigurera en skriptuppgift för att köra de CLI-kommandon som behövs för att starta de huvudlösa webbläsarinstanserna.
5. Kör testerna från slutpunkt till slutpunkt i pipelinestegen tillsammans med dina enhetstester.
6. Publicera resultaten med hjälp av samma publicera testresultat-uppgift tillsammans med dina enhetstester.

Paketera webbappar

Paketera program för att paketera alla dina programmoduler med mellanliggande utdata och beroenden i statiska tillgångar som är redo för distribution. Lägg till en pipelinefas efter kompilering och tester för att köra ett verktyg som webpack eller ng build med hjälp av Angular CLI.

I det första exemplet anropas webpack. Om du vill ha det här arbetet kontrollerar du att webpack det är konfigurerat som ett utvecklingsberoende i din package.json projektfil. Detta körs webpack med standardkonfigurationen om du inte har en webpack.config.js fil i rotmappen för projektet.

- script: webpack

I nästa exempel används npm-aktiviteten för att anropa npm run build build skriptobjektet som definierats i projektet package.json. Med hjälp av skriptobjekt i projektet flyttas logiken för bygget till källkoden och ut ur pipelinen.

- script: npm run build

Implementera JavaScript-ramverk

Angular

För Angular-appar kan du inkludera Angular-specifika kommandon som ng-test, ng build och ng e2e. Om du vill använda Angular CLI-kommandon i pipelinen installerar du angular/cli npm-paketet på byggagenten.

Kommentar

På Microsoft-värdbaserade Linux-agenter förordar du kommandot med sudo, till exempel sudo npm install -g.

- script: |
    npm install -g @angular/cli
    npm install
    ng build --prod

För tester i pipelinen som kräver att en webbläsare körs, till exempel ng-testkommandot i startappen, som kör Karma, använder du en huvudlös webbläsare i stället för en standardwebbläsare. I Angular-startappen:

1. browsers Ändra posten i din karma.conf.js projektfil från browsers: ['Chrome'] till browsers: ['ChromeHeadless'].

2. singleRun Ändra posten i din karma.conf.js projektfil från värdet false till true. Den här ändringen hjälper dig att se till att Karma-processen stoppas när den har körts.

React och Vue

Alla beroenden för dina React- och Vue-appar samlas in i din package.json-fil . Din azure-pipelines.yml-fil innehåller standardskriptet för Node.js:

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm run build
  displayName: 'npm build'

Byggfilerna finns i en ny mapp, dist (för Vue) eller build (för React). Det här kodfragmentet skapar en artefakt – www – som är redo för lansering. Den använder aktiviteterna Node Installer, Copy Files och 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

Släpp genom att peka versionsuppgiften dist på artefakten eller build och använda Azure Web App Deploy-uppgiften.

Webpack

Du kan använda en webpack-konfigurationsfil för att ange en kompilator, till exempel Babel eller TypeScript, för att transpilera JSX eller TypeScript till oformaterad JavaScript och paketera din app.

- script: |
    npm install webpack webpack-cli --save-dev
    npx webpack --config webpack.config.js

Skapa aktivitetslöpare

Det är vanligt att använda Gulp eller Grunt som uppgiftslöpare för att skapa och testa en JavaScript-app.

Klunk

Gulp förinstalleras på Microsoft-värdbaserade agenter. gulp Kör kommandot i YAML-filen:

- script: gulp                       # include any additional options that are needed

Om stegen i gulpfile.js-filen kräver autentisering med ett npm-register:

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: gulp                       # include any additional options that are needed

Lägg till uppgiften Publicera testresultat för att publicera JUnit- eller xUnit-testresultat på servern.

- task: PublishTestResults@2
  inputs:
    testResultsFiles: '**/TEST-RESULTS.xml'
    testRunTitle: 'Test results for JavaScript using gulp'

Lägg till aktiviteten Publicera kodtäckningsresultat för att publicera kodtäckningsresultat till servern. Du hittar täckningsmått i byggsammanfattningen och du kan ladda ned HTML-rapporter för ytterligare analys.

- task: PublishCodeCoverageResults@1
  inputs: 
    codeCoverageTool: Cobertura
    summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'
    reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage'

Grunt

Grunt förinstalleras på Microsoft-värdbaserade agenter. Så här kör du grunt-kommandot i YAML-filen:

- script: grunt                      # include any additional options that are needed

Om stegen i Gruntfile.js filen kräver autentisering med ett npm-register:

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: grunt                      # include any additional options that are needed

Paketera och leverera din kod

När du har skapat och testat appen kan du ladda upp byggutdata till Azure Pipelines, skapa och publicera ett npm- eller Maven-paket eller paketera byggutdata till en .zip fil för distribution till ett webbprogram.

Publicera filer till Azure Pipelines

Om du vill ladda upp hela arbetskatalogen med filer använder du aktiviteten Publicera byggartefakter och lägger till följande i azure-pipelines.yml filen.

- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(System.DefaultWorkingDirectory)'

Om du vill ladda upp en delmängd filer kopierar du först de filer som behövs från arbetskatalogen till en mellanlagringskatalog med uppgiften Kopiera filer och använder sedan aktiviteten Publicera byggartefakter.

- task: CopyFiles@2
  inputs:
    SourceFolder: '$(System.DefaultWorkingDirectory)'
    Contents: |
      **\*.js
      package.json
    TargetFolder: '$(Build.ArtifactStagingDirectory)'

- task: PublishBuildArtifacts@1

Publicera en modul till ett npm-register

Om projektets utdata är en npm modul för användning av andra projekt och inte ett webbprogram använder du npm-aktiviteten för att publicera modulen till ett lokalt register eller till det offentliga npm-registret. Ange en unik kombination av namn/version varje gång du publicerar.

Exempel

Det första exemplet förutsätter att du hanterar versionsinformation (till exempel via en npm-version) genom ändringar package.json i filen i versionskontroll. I följande exempel används skriptuppgiften för att publicera till det offentliga registret.

- script: npm publish

Nästa exempel publicerar till ett anpassat register som definierats i lagringsplatsens .npmrc fil. Konfigurera en npm-tjänstanslutning för att mata in autentiseringsuppgifter i anslutningen när bygget körs.

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useExternalRegistry
     publishEndpoint: https://my.npmregistry.com

Det sista exemplet publicerar modulen till ett Azure DevOps Services-pakethanteringsflöde.

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useFeed
     publishFeed: https://my.npmregistry.com

Mer information om versionshantering och publicering av npm-paket finns i Publicera npm-paket och Hur kan jag version mina npm-paket som en del av byggprocessen?.

Distribuera en webbapp

Om du vill skapa ett .zip filarkiv som är redo för publicering till en webbapp använder du uppgiften Arkivfiler :

- task: ArchiveFiles@2
  inputs:
    rootFolderOrFile: '$(System.DefaultWorkingDirectory)'
    includeRootFolder: false

Information om hur du publicerar det här arkivet till en webbapp finns i Distribution av Azure-webbappar.

Skapa och push-överföra avbildning till containerregister

När källkoden har skapats och enhetstesterna har genomförts kan du även skapa en avbildning och skicka den till ett containerregister.

Felsöka

Om du kan bygga projektet på utvecklingsdatorn men har problem med att skapa det i Azure Pipelines kan du utforska följande potentiella orsaker och korrigerande åtgärder:

• Kontrollera att versionerna av Node.js och aktivitetslöparen på utvecklingsdatorn matchar dem i agenten. Du kan inkludera kommandoradsskript som i pipelinen för att kontrollera vad som node --version är installerat på agenten. Använd antingen installationsprogrammet för nodverktyget (som beskrivs i den här vägledningen) för att distribuera samma version på agenten eller kör npm install kommandon för att uppdatera verktygen till önskade versioner.

• Om dina versioner misslyckas tillfälligt när du återställer paket har npm-registret antingen problem eller så finns det nätverksproblem mellan Azure-datacentret och registret. Vi kan inte kontrollera dessa faktorer. Utforska om användning av Azure Artifacts med ett npm-register som en överordnad källa förbättrar tillförlitligheten för dina versioner.

• Om du använder nvm för att hantera olika versioner av Node.js kan du byta till uppgiften Installationsprogram för nodverktyg i stället. (nvm installeras av historiska skäl på macOS-avbildningen.) nvm hanterar flera Node.js versioner genom att lägga till gränssnittsalias och ändra PATH, vilket interagerar dåligt med hur Azure Pipelines kör varje uppgift i en ny process.

  Uppgiften Installationsprogram för nodverktyget hanterar den här modellen korrekt. Men om ditt arbete kräver användning av nvmkan du lägga till följande skript i början av varje pipeline:

  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 Sedan fungerar andra kommandoradsverktyg för resten av pipelinejobbet. I varje steg där du använder nvm kommandot startar du skriptet med följande kod:

  - bash: |
      . ${NVM_DIR}/nvm.sh
      nvm <command>
  

Vanliga frågor

F: Var kan jag lära mig mer om Azure Artifacts och pakethanteringstjänsten?

S: Pakethantering i Azure Artifacts

F: Var kan jag lära mig mer om uppgifter?

S: Bygg-, versions- och testuppgifter

F: Hur åtgärdar jag ett pipelinefel med meddelandet "FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed – JavaScript heap out of memory"?

S: Den här feltypen inträffar när Node.js-paketet överskrider minnesanvändningsgränsen. Lös problemet genom att lägga till en variabel som NODE_OPTIONS och tilldela den värdet --max_old_space_size=16384.

F: Hur kan jag version mina npm-paket som en del av byggprocessen?

S: Ett alternativ är att använda en kombination av versionskontroll och npm-version. I slutet av en pipelinekörning kan du uppdatera lagringsplatsen med den nya versionen. I den här YAML-filen finns en GitHub-lagringsplats och paketet distribueras till npmjs. Bygget misslyckas om det finns ett matchningsfel mellan paketversionen på npmjs och package.json filen.

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