Condividi tramite


Pipeline per applicazioni JavaScript

Questo articolo illustra il funzionamento di Azure Pipelines con le app JavaScript. Gli agenti ospitati da Microsoft preinstallare gli strumenti comuni di compilazione, test e distribuzione javaScript, ad esempio npm, Node.js, Yarn e Gulp senza che sia necessario configurare alcuna infrastruttura. È anche possibile configurare agenti autogestiti.

Per creare rapidamente una pipeline per JavaScript, vedere la guida introduttiva a JavaScript.

Programmi di installazione dello strumento Node

Per installare Node.js e versioni npm non preinstallate o per installare gli strumenti negli agenti self-hosted:

Per installare una versione Node.js specifica, aggiungere il codice seguente al file azure-pipelines.yml :

- task: UseNode@1
  inputs:
    version: '16.x' # replace with the version you need

Nota

Questa attività può richiedere tempi significativi di aggiornamento a una versione secondaria più recente ogni volta che viene eseguita la pipeline. Gli agenti ospitati da Microsoft vengono aggiornati regolarmente, quindi usare questa attività solo per installare versioni di Node specifiche che non sono preinstallate. Per scoprire quali Node.js e le versioni npm sono preinstallate in agenti ospitati da Microsoft, vedere Software.

Usare più versioni dei nodi

È possibile usare l'attività Usa l’ecosistema Node.js v1 con una matrix strategia per costruire e testare l'app su più versioni di Node.js. Per ulteriori informazioni, vedere Configurazione multi-task.

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

Installazione dello strumento di dipendenza

Se nel progetto sono presenti strumenti di dipendenza di sviluppo package.json o package-lock.json file, installare gli strumenti e le dipendenze tramite npm. Il file di progetto definisce la versione esatta degli strumenti, indipendentemente dalle altre versioni esistenti nell'agente di compilazione.

Per installare questi strumenti nell'agente di compilazione, usare uno script, l'attività npm o un'attività della riga di comando nella pipeline.

Per usare uno script:

- script: npm install --only=dev

Per usare l'attività npm:

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

Gli strumenti installati in questo modo usano l'esecutore di pacchetti npm npx, che rileva gli strumenti nella sua risoluzione del PATH. Nell'esempio seguente viene chiamato il mocha test runner e viene usata la versione della dipendenza di sviluppo anziché la versione installata a livello globale tramite npm install -g.

- script: npx mocha

Per installare gli strumenti necessari per il progetto che non sono impostati come dipendenze di sviluppo in package.json, chiamare npm install -g da uno script nella pipeline. Nell'esempio seguente viene installata la versione più recente dell'interfaccia della riga di comando di Angular usando npm. Altri script nella pipeline possono quindi usare i comandi Angular ng .

- script: npm install -g @angular/cli

Nota

Negli agenti Linux ospitati da Microsoft anteporre al comando sudo, ad esempio sudo npm install -g.

Queste attività di installazione degli strumenti vengono eseguite ogni volta che viene eseguita la pipeline, quindi tenere presente il loro impatto sui tempi di compilazione. Se il sovraccarico influisce seriamente sulle prestazioni di compilazione, prendere in considerazione l'uso di agenti self-hosted preconfigurati con le versioni degli strumenti necessarie.

Nota

Queste attività di installazione degli strumenti vengono eseguite ogni volta che viene eseguita la pipeline, quindi tenere presente il loro impatto sui tempi di compilazione.

Download dei pacchetti di dipendenze

È possibile usare Yarn o Azure Artifacts per scaricare i pacchetti dal registro npm pubblico o da un registro npm privato specificato in un file *.npmrc . Per specificare un registro npm, aggiungere il relativo URL al file *.npmrc nel repository di codice.

Usare npm

È possibile usare npm per scaricare i pacchetti di compilazione nella pipeline nei modi seguenti:

  • Per il modo più semplice per scaricare i pacchetti senza autenticazione, eseguire npm installdirettamente .
  • Per usare un registro autenticato, aggiungere l'attività npm .
  • Per eseguire npm install dall'interno degli strumenti di esecuzione attività Gulp, Grunt o Maven, usare il task npm authenticate.

Nota

Se il feed npm usa l'autenticazione, è necessario creare una connessione al servizio npm nella scheda Servizi nelle impostazioni del progetto Azure DevOps per gestire le credenziali.

Per installare direttamente i pacchetti npm, usare lo script seguente in azure-pipelines.yml. Se l'agente di compilazione non necessita di dipendenze di sviluppo, è possibile velocizzare i tempi di compilazione aggiungendo l'opzione --only=prod a npm install.

- script: npm install --only=prod

Per usare un registro privato specificato nel file *.npmrc , aggiungere l'attività Npm@1 a azure-pipelines.yml.

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

Per passare le credenziali del registro ai comandi npm tramite i task runner, ad esempio Gulp, aggiungere il task npmAuthenticate@0 a azure-pipelines.yml prima di chiamare il task runner.

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

Nota

Gli agenti ospitati da Microsoft usano un nuovo computer con ogni compilazione. Il ripristino delle dipendenze può richiedere molto tempo. Per attenuare il problema, è possibile usare Azure Artifacts o un agente self-hosted con la cache dei pacchetti.

Se le compilazioni non riescono occasionalmente a causa di problemi di connessione quando si ripristinano pacchetti dal registro npm, è possibile usare Azure Artifacts con origini upstream per memorizzare nella cache i pacchetti. Azure Artifacts usa automaticamente le credenziali della pipeline, normalmente derivate dall'account del servizio di compilazione della raccolta di progetti .

Nota

Il ripristino delle dipendenze può richiedere molto tempo. Per attenuare il problema, è possibile usare Azure Artifacts o un agente self-hosted con la cache dei pacchetti.

Se le compilazioni non riescono occasionalmente a causa di problemi di connessione quando si ripristinano pacchetti dal registro npm, è possibile usare Azure Artifacts con origini upstream per memorizzare nella cache i pacchetti. Azure Artifacts usa automaticamente le credenziali della pipeline, normalmente derivate dall'account del servizio di compilazione della raccolta di progetti .

Usare Yarn

Usare uno script per installare Yarn per ripristinare le dipendenze. Yarn è preinstallato in alcuni agenti ospitati da Microsoft. È possibile installare e configurare Yarn in agenti self-hosted come qualsiasi altro strumento.

- script: yarn install

È anche possibile usare il CLI o l'attività Bash nella pipeline per richiamare Yarn.

Compilatori JavaScript

Le app JavaScript usano compilatori come Babel e il compilatore TypeScripttsc per convertire il codice sorgente in versioni utilizzabili dal runtime Node.js o nei Web browser. Se nel progetto è configurato un oggetto scriptpackage.json file per eseguire il compilatore, è possibile richiamarlo nella pipeline.

- script: npm run compile

È anche possibile chiamare i compilatori direttamente dalla pipeline usando uno script. Questi comandi vengono eseguiti dalla radice del repository del codice sorgente clonato.

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

È possibile usare l'attività npm per compilare il codice se il progetto package.json definisce uno script di compilazione. Se non si definisce uno script di compilazione, è possibile usare l'attività Bash per compilare il codice.

Test unitario

È possibile configurare le pipeline per eseguire i test JavaScript in modo che producano risultati nel formato XML JUnit. È quindi possibile pubblicare i risultati usando l'attività Pubblica risultati test .

Se il framework di test non supporta l'output JUnit, aggiungere il supporto tramite un modulo di creazione di report partner, ad esempio mocha-junit-reporter. È possibile aggiornare lo script di test per usare il reporter JUnit oppure passare tali opzioni nella definizione dell'attività se il reporter supporta le opzioni della riga di comando.

Nella tabella seguente sono elencati gli strumenti di esecuzione dei test usati più di frequente e i reporter che è possibile usare per produrre risultati XML:

Test Runner Generatori di rapporti XML
Mocha mocha-junit-reporter
cioeca-multi-reporter
Gelsomino reporter di gelosomini
Jest jest-junit
jest-junit-reporter
Karma karma-junit-reporter
Ava tap-xunit

Nell'esempio seguente viene usato mocha-junit-reporter e viene richiamato mocha test direttamente usando uno script. Questo script genera l'output XML JUnit nel percorso predefinito di ./test-results.xml.

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

Se è stato definito uno test script nel file dipackage.json del progetto, è possibile richiamarlo usando npm test.

- script: npm test

Pubblica risultati dei test

Per pubblicare i risultati dei test, usare l'attività Pubblica risultati test .

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

Pubblicare i risultati del code coverage

Se gli script di test eseguono uno strumento di copertura del codice come Istanbul, aggiungere l'attività Pubblica i risultati della copertura del codice. È quindi possibile visualizzare le metriche di copertura nel riepilogo della compilazione e scaricare i report HTML per ulteriori analisi.

L'attività prevede l'output dei report Cobertura o JaCoCo. Assicurarsi che lo strumento di code coverage venga eseguito con le opzioni necessarie per generare l'output corretto, ad esempio --report cobertura.

Nell'esempio seguente si usa l'interfaccia della riga di comando Istanbul nyc insieme a mocha-junit-reporter e richiama 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'

Test del browser da capo a fine

La pipeline può usare strumenti come Protractor o Karma per eseguire test su browser senza interfaccia e quindi pubblicare i risultati dei test. Per configurare i risultati di test e pubblicazione del browser, seguire questa procedura:

  1. Installare un driver per il test di browser senza interfaccia, come Chrome senza interfaccia o Firefox, oppure uno strumento di simulazione del browser, come PhantomJS, sul agente di compilazione.
  2. Configurare il framework di test per usare l'opzione headless browser o driver in base alla documentazione dello strumento.
  3. Configurare il framework di test per produrre i risultati in formato JUnit, generalmente utilizzando un plug-in o una configurazione del tool reporter.
  4. Aggiungere uno script o un'attività CLI per avviare le istanze del browser headless.
  5. Eseguire i test end-to-end nelle fasi della pipeline insieme agli unit test.
  6. Pubblica i risultati insieme ai test unitari usando la stessa attività Pubblica risultati dei test.

Imballaggio e consegna

Dopo aver compilato e testato l'app, è possibile:

  • Caricare l'output di compilazione in Azure Pipelines.
  • Creare e pubblicare un pacchetto npm o Maven.
  • Creare un pacchetto dell'output di compilazione in un archivio ZIP per la distribuzione in un'applicazione Web.

Pubblicare file in Azure Pipelines

Per caricare l'intera directory di lavoro, aggiungere l'attività Pubblica artefatti di build al file azure-pipelines.yml.

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

Per caricare un sottoinsieme di file, copiare prima i file necessari dalla directory di lavoro in una directory di staging con l'attività Copia file; quindi utilizzare l'attività Pubblica artefatti di compilazione.

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

- task: PublishBuildArtifacts@1

Pubblicare un modulo in un registro npm

Se l'output del progetto è un npm modulo per altri progetti da usare e non è un'applicazione Web, usare l'attività npm per pubblicare il modulo in un registro locale o nel registro npm pubblico. Specificare una combinazione di nome/versione univoca ogni volta che si pubblica.

Nell'esempio seguente viene usato lo script per pubblicare nel registro npm pubblico. Nell'esempio si presuppone che si gestisca l'informazione sulla versione, come npm, tramite un file package.json nel controllo della versione.

- script: npm publish

Nell'esempio seguente viene pubblicato in un registro personalizzato definito nel file *.npmrc del repository. Configurare una connessione al servizio npm per inserire le credenziali di autenticazione nella connessione durante l'esecuzione della compilazione.

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

L'esempio seguente pubblica il modulo in un feed di gestione pacchetti di Azure DevOps Services.

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

Per altre informazioni sul controllo delle versioni e sulla pubblicazione di pacchetti npm, vedere Pubblicare pacchetti npm e Come è possibile eseguire la versione dei pacchetti npm come parte del processo di compilazione.

Creare un pacchetto e distribuire un'app Web

È possibile creare un pacchetto di applicazioni per aggregare tutti i moduli con output intermedi e dipendenze in asset statici pronti per la distribuzione. Aggiungere una fase della pipeline dopo la compilazione e i test per eseguire uno strumento come webpack o il comando ng build dell'Angular CLI.

Nell'esempio seguente viene chiamato webpack. Per il corretto funzionamento di questo processo, assicurarsi che webpack sia configurato come dipendenza di sviluppo nel file di progetto package.json . Questo script viene eseguito webpack con la configurazione predefinita, a meno che non sia presente un filewebpack.config.js nella cartella radice del progetto.

- script: webpack

Nell'esempio seguente viene npm run build usato per chiamare l'oggetto build script definito nel file dipackage.json del progetto. L'uso dell'oggetto script nel progetto sposta la logica di compilazione nel codice sorgente e all'esterno della pipeline.

- script: npm run build

È anche possibile usare CLI o l'attività Bash nella pipeline per richiamare lo strumento di creazione pacchetti, ad esempio webpack o Angular.ng build

Per creare un archivio di file *.zip pronto per la pubblicazione in un'app Web, usare l'attività Archivia file .

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

Per pubblicare questo archivio in un'app Web, vedere Distribuire nel servizio app di Azure usando Azure Pipelines.

Framework JavaScript

È possibile installare pacchetti nella pipeline per supportare vari framework JavaScript.

Angular

Per le app Angular, è possibile eseguire comandi specifici di Angular, ng testad esempio , ng builde ng e2e. Per usare i comandi dell'interfaccia della riga di comando di Angular nella pipeline, installare il pacchetto npm angular/cli nell'agente di compilazione.

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

Nota

Negli agenti Linux ospitati da Microsoft anteporre al comando sudo, ad esempio sudo npm install -g.

Per i test nella pipeline che richiedono l'esecuzione di un browser, ad esempio l'esecuzione di Karma con il ng test comando , usare un browser headless anziché un browser standard. Nell'app di avvio Angular:

  • Modificare la browsers voce nel file di progetto karma.conf.js da browsers: ['Chrome'] a browsers: ['ChromeHeadless'].
  • Modificare la singleRun voce nel file di progetto karma.conf.js da false a true. Questa modifica aiuta ad assicurare che il processo Karma si arresti dopo che è stato eseguito.

React e Vue

Tutte le dipendenze per le app React e Vue vengono acquisite nel file package.json . Il file azure-pipelines.yml contiene gli script standard npm .

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

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

I file di compilazione si trovano in una nuova cartella, dist per Vue o build per React. Nell'esempio seguente viene compilato un artefatto, www, pronto per il rilascio. La pipeline usa le attività Usa Node.js, Copia file e Pubblica artefatti di compilazione .

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

Per rilasciare l'app, punta l'attività di rilascio all'elemento dist o build e usa l'attività App Web di Azure.

Webpack

È possibile usare un file di configurazione webpack per specificare un compilatore, ad esempio Babel o TypeScript, per transpile JavaScript XML (JSX) o TypeScript in JavaScript normale e per aggregare l'app.

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

Strumenti di esecuzione attività di compilazione

È comune usare Gulp o Grunt come task runner per costruire e testare app JavaScript.

Gulp

Gulp è preinstallato in agenti ospitati da Microsoft.

È possibile eseguire il gulp comando nel file della pipeline YAML.

- script: gulp # add any needed options

Se i passaggi nel file digulpfile.js richiedono l'autenticazione con un registro npm, aggiungere l'attività di autenticazione npm .

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

- script: gulp

Per pubblicare i risultati del test JUnit o xUnit nel server, aggiungere l'attività Pubblica risultati test .

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

Per pubblicare i risultati della copertura del codice sul server, aggiungere l'attività Pubblica risultati della copertura del codice. È possibile trovare le metriche di copertura nel riepilogo della compilazione ed è possibile scaricare i report HTML per ulteriori analisi.

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

Grunt

Grunt è preinstallato in agenti ospitati da Microsoft.

È possibile eseguire il grunt comando nel file YAML.

- script: grunt # add any needed options

Se i passaggi nel file diGruntfile.js richiedono l'autenticazione con un registro npm, aggiungere l'attività di autenticazione npm .

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

- script: grunt

Risoluzione dei problemi

Se è possibile compilare il progetto nel computer di sviluppo ma non è possibile compilarlo in Azure Pipelines, esplorare le possibili cause e le azioni correttive seguenti.

  • Verifica che le versioni di Node.js e del gestore delle attività nel computer di sviluppo corrispondano a quelle presenti sull'agente.

    È possibile includere script della riga di comando, ad node --version esempio nella pipeline, per controllare le versioni installate nell'agente. Usare l'attività Use Node.js per installare la stessa versione nell'agente oppure eseguire npm install comandi per aggiornare le versioni dello strumento.

  • Se le compilazioni hanno esito negativo in modo intermittente durante il ripristino dei pacchetti, il registro npm presenta problemi o si verificano problemi di rete tra il data center di Azure e il Registro di sistema. Scoprire se l'uso di Azure Artifacts con un registro npm come origine upstream migliora l'affidabilità delle compilazioni.

  • Se si usa nvm per gestire versioni diverse di Node.js, è consigliabile passare all'attività Usa Node.js (UseNode@1). nvm viene installato per motivi cronologici nell'immagine macOS. nvm gestisce più versioni Node.js aggiungendo alias della shell e modificando PATH, che interagisce in modo non corretto con il modo in cui Azure Pipelines esegue ogni attività in un nuovo processo. Per altre informazioni, vedere Esecuzioni di pipeline.

    L'attività Use Node.js gestisce correttamente questo modello. Tuttavia, se il lavoro richiede l'uso di nvm, puoi aggiungere lo script seguente all'inizio di ogni pipeline.

    steps:
    - bash: |
        NODE_VERSION=16  # or your preferred version
        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"
    

    Quindi, node e altri strumenti da riga di comando funzionano per il resto del processo della pipeline. In ogni passaggio in cui si usa il nvm comando avviare lo script con il codice seguente:

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

Domande frequenti

Come è possibile correggere un errore della pipeline con il messaggio "ERRORE IRREVERSIBILE: CALL_AND_RETRY_LAST allocazione non riuscita - Heap JavaScript insufficiente nella memoria"?

Questo tipo di errore si verifica quando il pacchetto Node.js supera il limite di utilizzo della memoria. Per risolvere il problema, aggiungere una variabile come NODE_OPTIONS e assegnarla un valore di --max_old_space_size=16384.

Come è possibile eseguire la versione dei pacchetti npm come parte del processo di compilazione?

Un'opzione consiste nell'usare una combinazione di controllo della versione e versione npm. Al termine di un'esecuzione della pipeline, è possibile aggiornare il repository con la nuova versione. La pipeline YAML seguente include un repository GitHub e il pacchetto viene distribuito in npmjs. La compilazione ha esito negativo se si verifica una mancata corrispondenza tra la versione del pacchetto in npmjs e il file 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