如何将npm包及其依赖部署至GitLab Registry（离线构建场景）

1. 准备外网环境并登录GitLab Registry #

• 在有网络的机器上先安装项目完整依赖：npm install，确保node_modules目录包含所有层级的依赖包
• 登录GitLab私有Registry（需使用具备write_package_registry权限的个人访问令牌）：

  npm login --registry=https://gitlab.com/api/v4/projects/xxxxx/packages/npm/
  

  依次输入GitLab用户名、个人访问令牌、绑定邮箱完成登录

2. 批量发布所有依赖包到GitLab Registry #

GitLab Registry支持发布任意合法npm包，我们可以遍历node_modules下的所有包，打包后逐一发布。

方法一：Shell脚本批量处理 #

创建publish-deps.sh脚本：

#!/bin/bash

REGISTRY="https://gitlab.com/api/v4/projects/xxxxx/packages/npm/"

# 遍历所有顶级依赖（含@aws-sdk这类组织包）
for pkg in node_modules/* node_modules/@*/*; do
  if [ -f "$pkg/package.json" ]; then
    cd "$pkg" || continue
    PKG_NAME=$(jq -r '.name' package.json)
    PKG_VERSION=$(jq -r '.version' package.json)
    echo "Processing $PKG_NAME@$PKG_VERSION"
    
    # 生成tar包
    npm pack
    
    # 发布到GitLab Registry
    TAR_FILE=$(ls *.tgz)
    npm publish "$TAR_FILE" --registry="$REGISTRY"
    
    cd - > /dev/null
    echo "-------------------------"
  fi
done

• 确保已安装jq工具（用于解析package.json）：Debian/Ubuntu用sudo apt install jq，Mac用brew install jq
• 赋予脚本执行权限：chmod +x publish-deps.sh
• 运行脚本：./publish-deps.sh

方法二：Node.js脚本处理（无需额外工具） #

创建publish-deps.js：

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

const REGISTRY = 'https://gitlab.com/api/v4/projects/xxxxx/packages/npm/';
const rootDir = __dirname;
const nodeModulesDir = path.join(rootDir, 'node_modules');

// 遍历目录处理所有包
function processDir(dir) {
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      // 处理组织类包（如@aws-sdk）的子目录
      if (entry.name.startsWith('@')) {
        processDir(fullPath);
      } else {
        const pkgJsonPath = path.join(fullPath, 'package.json');
        if (fs.existsSync(pkgJsonPath)) {
          publishPackage(fullPath);
        }
      }
    }
  }
}

// 发布单个包
function publishPackage(pkgDir) {
  console.log(`开始处理：${pkgDir}`);
  try {
    process.chdir(pkgDir);
    // 生成tar包
    execSync('npm pack', { stdio: 'inherit' });
    // 找到生成的tar包
    const tarFiles = fs.readdirSync('.').filter(file => file.endsWith('.tgz'));
    if (tarFiles.length === 0) {
      console.log('未生成tar包，跳过');
      return;
    }
    // 发布到Registry
    execSync(`npm publish ${tarFiles[0]} --registry=${REGISTRY}`, { stdio: 'inherit' });
    console.log('发布成功');
  } catch (err) {
    console.error('发布失败：', err.message);
  } finally {
    process.chdir(rootDir);
    console.log('-------------------------\n');
  }
}

// 启动遍历
processDir(nodeModulesDir);

• 运行脚本：node publish-deps.js

3. 配置离线构建环境 #

在项目根目录创建/修改.npmrc文件，强制所有包从GitLab Registry拉取：

@npm-project:registry=https://gitlab.com/api/v4/projects/xxxxx/packages/npm/
@aws-sdk:registry=https://gitlab.com/api/v4/projects/xxxxx/packages/npm/
# 设置全局默认Registry，确保所有公共包也从私有源拉取
registry=https://gitlab.com/api/v4/projects/xxxxx/packages/npm/
# 构建机器需配置认证令牌（替换为你的GitLab个人访问令牌）
//gitlab.com/api/v4/projects/xxxxx/packages/npm/:_authToken=<你的访问令牌>

4. 验证离线构建 #

在无网络环境下执行：

npm install

此时所有依赖将直接从GitLab Registry拉取，无需访问外网。

注意事项 #

• 个人访问令牌需同时拥有write_package_registry（发布权限）和read_package_registry（拉取权限）
• 重复运行发布脚本时，已存在的包版本会发布失败，属于正常现象可忽略
• 依赖更新后，需在有网络环境重新安装依赖，再重新发布新版本到GitLab Registry

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