将 npm 项目连接到 Azure Artifacts 源

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

Azure Artifacts 使开发人员可以从源和公共注册表（如 npmjs.com）发布和安装各种包类型。 若要使用 Azure Artifacts 进行身份验证，必须配置 npm 配置文件。 此文件包含 npm 使用的源 URL 和凭据，提供自定义 npm 客户端行为的选项，例如设置代理、定义默认包位置或配置专用包源。 .npmrc 文件通常位于用户的主目录中，但也可在项目级别创建以替代默认设置。 通过修改 .npmrc 文件，用户可以个性化其 npm 体验以满足其特定要求。

先决条件

• Azure DevOps 组织和项目。 创建 组织 或 项目 （如果尚未创建）。

• Azure Artifacts 源。 如果你没有源，请创建一个新源。

• 下载并安装 Node.js 和 npm。

项目设置

对于最佳做法，建议使用两个单独的配置文件。 第一个用于使用 Azure Artifacts 进行身份验证，而第二个项目则存储在本地并保存凭据。

若要设置第二个文件，只需将其放在开发计算机上的主目录中，并包括所有注册表凭据。 这样一来，npm 客户端可以轻松访问凭据进行身份验证，使你能够在确保凭据安全的同时共享配置文件。

以下步骤将指导你设置第一个配置文件：

Windows

1. 登录到 Azure DevOps 组织，并导航到你的项目。

2. 选择“项目”，然后选择连接源。

   

3. 从左侧导航窗格中选择 npm 。

4. 如果这是首次将 Azure Artifacts 与 npm 配合使用，请选择“ 获取工具 ”并按照说明安装必备组件。

5. 按照 Project 安装程序中的说明连接到源。

   

其他

1. 在项目的目录中、package.json文件所在的同一 目录中添加 .npmrc 文件，并将以下代码片段复制到其中。

   registry=https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/ 
   
   always-auth=true
   

设置凭据

1. 将以下代码片段复制到用户级 npmrc 文件中：

   • 组织范围的源：

     ; begin auth token
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:email=npm requires email to be set but doesn't use the value
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:username=[ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:email=npm requires email to be set but doesn't use the value
     ; end auth token
     

   • 项目范围的源：

     ; begin auth token
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:email=npm requires email to be set but doesn't use the value
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:email=npm requires email to be set but doesn't use the value
     ; end auth token
     

2. 使用打包读取和写入范围生成个人访问令牌。

3. 按如下所示对新生成的个人访问令牌进行编码：

   1. 在命令提示符窗口中运行以下命令，然后在出现提示时粘贴个人访问令牌：

      node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"
      

      还可以使用以下命令将个人访问令牌转换为 Base 64。

      • Linux/Mac：

        echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64
        

   2. 复制 Base 64 编码值。

4. 将用户 .npmrc 文件中的 [BA标准版64_ENCODED_PERSONAL_ACCESS_TOKEN] 值替换为步骤 3 中的个人访问令牌。

提示

范围和上游源支持在 .npmrc 文件中使用多个注册表。

管道身份验证

若要使用管道进行身份验证，Azure Artifacts 建议使用 npm 身份验证任务。

使用 gulp 或 Grunt 等任务运行程序时，必须在管道开始时包括 npm 身份验证任务。 此操作可确保将凭据注入到项目的 .npmrc 文件中并在整个管道运行中保留，从而使后续步骤能够访问配置文件中的凭据。

经典

1. 导航到项目，选择 “管道”，然后选择管道定义。

2. 选择“编辑”以修改管道。

3. 选择 + 以向管道添加新任务。

   

4. 搜索 npm 身份验证任务，然后选择“添加”。

   

5. 选择 .npmrc 文件，然后在完成后选择“保存并排队”。

   

YAML

- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc                ## Path to the npmrc file
    customEndpoint: #Optional          ## Comma-separated list of npm service connection names for registries from external organizations. For registries in your org, leave this blank

注意

要让管道访问源，请确保生成服务角色在源设置中设置为源和上游读取者（参与者）。

注意

如果组织使用的是防火墙或代理服务器，请确保允许相应的域 URL。 有关详细信息，请参阅 允许的 IP 地址和域 URL 。

疑难解答

vsts-npm-auth 无法识别

如果在项目执行过程中遇到以下错误：

• Cmd：'vsts-npm-auth' is not recognized as an internal or external command, operable program or batch file.

• PowerShell：vsts-npm-auth : The term 'vsts-npm-auth' is not recognized as the name of a cmdlet, function, script file, or operable program.

然后，npm modules 文件夹可能尚未添加到路径。 若要解决此问题，请重新运行Node.js设置，并确保选择该 Add to PATH 选项。

或者，可以通过在命令提示符或 $env:APPDATA\npm PowerShell 中将 PATH 变量修改为%APPDATA%\npm路径，将 npm modules 文件夹添加到路径。

无法进行身份验证

如果遇到 E401 错误： code E401 npm ERR! Unable to authenticate. 使用 vsts-npm-auth-F 标志运行命令以重新进行身份验证。

vsts-npm-auth -config .npmrc -F

重置 vsts-npm-auth

按照以下步骤重置 vsts-npm-auth 凭据：

1. 卸载 vsts-npm-auth：

   npm uninstall -g vsts-npm-auth
   

2. 清除 npm 缓存：

   npm cache clean --force
   

3. 删除 .npmrc 文件。

4. 重新安装 vsts-npm-auth：

   npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false
   

相关文章

• 发布和还原 npm 包 （CLI）
• 发布 npm 包（YAML/经典）
• 使用来自 npmjs.com 的包