将 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 文件通常位于用户的主目录中，但也可在项目级别创建以替代默认设置。

先决条件

• Azure DevOps 组织。 免费创建一个。

• 一个 Azure DevOps 项目。 如果您没有源，请创建一个新项目。

• Azure Artifacts 源。 免费创建一个。

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

连接到源

Azure Artifacts 建议使用两个单独的配置文件。 第一个专用于使用 Azure Artifacts 进行身份验证，而第二个应保存在本地以存储凭据。 此方法允许你在确保凭据安全的同时共享配置文件。

若要设置第二个文件，只需将其放在开发计算机上的主目录中，并包括所有注册表凭据。 这使 npm 客户端能够轻松访问凭据进行身份验证。

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

Windows

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

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

   

3. 从左侧边栏中选择 npm 。 如果这是首次将 Azure Artifacts 与 npm 配合使用，请确保已安装必备组件。

4. 按照“项目设置”部分中的说明连接到源。

   

其他

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. 在命令提示符窗口中运行以下命令，然后在出现提示时粘贴个人访问令牌。 完成后，复制生成的 Base 64 编码值。

   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(); })"
   

4. 如果使用的是 Linux/Mac，则可以使用以下命令将个人访问令牌转换为 Base 64。 复制生成的 Base64 编码值。

   echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64
   

5. 将用户 .npmrc 文件中的占位符 [BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] 替换为从上一步获取的编码个人访问令牌。

提示

范围和上游源支持在 .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 无法识别

此错误表示尚未将 npm modules 文件夹添加到路径。 重新运行Node.js设置，并确保选择该 Add to PATH 选项。 或者，可以通过在命令提示符或 $env:APPDATA\npm PowerShell 中将 PATH 变量修改为%APPDATA%\npm路径，将 npm modules 文件夹添加到路径。

无法进行身份验证

• 错误：代码 E401 npm ERR！无法进行身份验证： -> 使用 -F 标志运行vsts-npm-auth命令以重新进行身份验证：

  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
   

无法发布

如果遇到 403 错误，则可能表示名称冲突。 在 Azure Artifacts 中，包是不可变的，这意味着将包发布到源后，其版本号将永久保留。 即使删除了它，也不能发布具有相同版本号的新包。 若要解决此问题，请更新package.json文件中的包版本，然后重试。

相关文章

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