Azure Synapse CI/CD中npx synapse-artifacts访问公网registry失败排查

问题背景 #

在Windows构建容器中搭建Azure Synapse工作区CI/CD流水线，计划使用synapse-artifacts工具验证Synapse工件并生成ARM模板。但"Validate Synapse Artifacts"步骤失败：已配置Azure Artifacts npm源、.npmrc和package.json，任务仍尝试从公网npm registry（registry.npmjs.org）下载包，因网络限制触发EACCES访问错误。

相关配置 #

流水线YAML #

- task: NodeTool@0
  inputs:
    versionSource: 'spec'
    versionSpec: '18.x'
  displayName: 'Install Node.js'

- task: npmAuthenticate@0
  displayName: Authenticate npm feed
  inputs:
    workingFile: $(Build.SourcesDirectory)/source/synapse/Package/.npmrc

- script: npm install
  displayName: Install npm packages
  workingDirectory: $(Build.SourcesDirectory)/source/synapse/Package

- script: |
    npx synapse-artifacts validate ^
      --path "$(Build.SourcesDirectory)/source/synapse" ^
      --workspace-name "$(SynapseWorkspaceName)"
  displayName: Validate Synapse Artifacts
  workingDirectory: $(Build.SourcesDirectory)/source/synapse/Package

- script: |
    npx synapse-artifacts generate ^
      --path "$(Build.SourcesDirectory)/source/synapse" ^
      --workspace-name "$(SynapseWorkspaceName)" ^
      --output-folder "$(Build.SourcesDirectory)/arm_output"
  displayName: Generate ARM Template
  workingDirectory: $(Build.SourcesDirectory)/source/synapse/Package

.npmrc文件 #

registry=https://xxxx.pkgs.visualstudio.com/<org>/_packaging/internal-npm-feed/npm/registry/
always-auth=true

package.json文件 #

{
  "name": "synapse-build",
  "version": "0.2.0",
  "private": true,
  "Dependencies": {
    "synapse-artifacts": "0.2.0"
  }
}

错误信息 #

npm ERR! code EACCES
npm ERR! syscall connect
npm ERR! FetchError: request to https://registry.npmjs.org/synapse-artifacts failed
reason: connect EACCES 192.0.2.7:443

疑问与解答 #

1. 为何npx synapse-artifacts尝试从公网npm registry下载，而非使用配置的Azure Artifacts源？ #

核心原因有两点：

• npx的 fallback 机制：npx执行时如果本地node_modules未找到目标包，会默认转向公网npm registry拉取。而你的package.json中依赖字段写成了大写的Dependencies，npm仅识别小写的dependencies，导致npm install未成功安装包，npx只能 fallback 到公网源。
• 配置作用范围问题：npmAuthenticate@0仅为指定路径的.npmrc做了认证，但npx执行时可能未正确读取该配置，或因全局.npmrc存在公网源配置而优先使用。

2. 在受限企业环境中执行synapse-artifacts validate的推荐方式是什么？ #

按以下步骤调整：

• 修复依赖配置：将package.json中的Dependencies改为小写的dependencies，确保npm能识别并安装依赖。
• 验证依赖安装结果：在npm install步骤后添加npm list synapse-artifacts命令，确认包已成功安装到本地node_modules。
• 全局配置私有源：在流水线开头添加全局npm源配置，确保所有npm/npx操作默认使用私有源：

  npm config set registry https://xxxx.pkgs.visualstudio.com/<org>/_packaging/internal-npm-feed/npm/registry/
  npm config set always-auth true
  

• 确认私有源包含目标包：确保Azure Artifacts源已同步或上传synapse-artifacts包，避免npm install因找不到包而失败。

3. 是否应从本地node_modules引用包而非使用npx？ #

是的，这是受限环境下的最优方案，具体实现方式有两种：

• 直接调用本地包路径：修改验证和生成步骤的脚本，直接指向node_modules中的工具：

  node node_modules/synapse-artifacts/bin/synapse-artifacts.js validate ^
    --path "$(Build.SourcesDirectory)/source/synapse" ^
    --workspace-name "$(SynapseWorkspaceName)"
  

• 使用npm scripts：在package.json中添加脚本：

  "scripts": {
    "validate": "synapse-artifacts validate --path \"../\" --workspace-name \"$(SynapseWorkspaceName)\"",
    "generate": "synapse-artifacts generate --path \"../\" --workspace-name \"$(SynapseWorkspaceName)\" --output-folder \"../../arm_output\""
  }
  

  然后流水线中执行：

  npm run validate
  

  两种方式都会优先使用本地node_modules中的包，不会触发公网拉取。

内容的提问来源于stack exchange，提问作者Partha