yz-npmrc-generator

自动生成 .npmrc 文件，用于配置私有 NPM 源认证信息，支持本地开发与 CI 构建。自动处理包作用域、认证信息、构建时安全挂载认证信息、Git 忽略等细节，提升开发与部署效率。

🚀 快速开始

无需安装，首次直接运行：

npx yz-npmrc-generator --registry-url https://your-registry-url/ --scopes "@your-scope"

.gen-npmrc.config.json 配置文件生成后，可直接执行：

npx yz-npmrc-generator

🪟 Windows 用户注意：

请在 Git Bash 或 WSL（Linux 子系统） 中运行上述命令

⚠️ Windows 用户可以在 CMD 或 PowerShell 中使用该工具，但请确保系统已安装 **Git Bash 或其他 Bash 环境，因为脚本本身依赖 Bash 执行

👉 推荐安装 Git for Windows

⚙️ 支持功能一览

• ✅ 支持本地开发模式，从 ~/.npmrc 中提取认证信息
• ✅ 支持 CI 模式，从环境变量中读取 用户名/密码 或 token
• ✅ 自动生成 .npmrc 文件并注入作用域 registry 与认证信息
• ✅ 自动追加 .npmrc 与脚本配置文件到 .gitignore / .dockerignore，防止 .npmrc 被提交或打包
• ✅ 自动检测安装 Docker Buildx 插件，用于 docker build 时使用 --secret 挂载 .npmrc，无痕使用 .npmrc（测试 CI docker 版本为：Linux + Docker Engine 24.0.2，docker-buildxbuilx 自动安装版本为：buildx-v0.11.2.linux-amd64），docker 版本过高可能存在插件不兼容的情况
• ✅ 自动生成 .gen-npmrc.config.json 文件保存配置，便于复用

🧾 参数说明（推荐通过 CLI 传入）

| 参数名 | 类型 | 是否必填 | 示例 | | ------------------ | ---------------- | ------------------ | ----------------------------------------------------------------- | | --registry-url | string | ✅ 必填 | https://unicomcdn-npm.pkg.coding.net/cdn-frontend/yunzhou-fe/ | | --scopes | string | ❌ 可选 | "@yunzhou-fe"或 "@foo,@bar"（逗号分隔多个 scope） |

如果未传入这些参数，将尝试读取当前目录下 .gen-npmrc.config.json 中的配置。

📦 环境变量说明（CI 模式）

CI 环境请提前设置以下环境变量：

| 变量名 | 说明 | | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | NPM_USER | NPM 登录用户名，例如 yunzhou-fe-xxxxx 若为 token_user或 placeholder表示使用 token | | NPM_TOKEN | 对应 token 或 base64 编码密码 | | REGISTRY_URL | 私有 npm registry 地址（等价于 --registry-url参数） | | SCOPE_LIST | NPM scope 列表，逗号分隔（等价于 --scopes参数，可选） |

若未设置 REGISTRY_URL，且无传参、无配置文件，将提示错误并退出。

方式二：REGISTRY_URL 、SCOPE_LIST 不传入，直接使用命令指定参数（和本地一致）：

npx yz-npmrc-generator --registry-url https://your-registry-url/ --scopes "@your-scope"

📝 .gen-npmrc.config.json 示例（由脚本自动生成）

{
  "registryUrl": "https://unicomcdn-npm.pkg.coding.net/cdn-frontend/yunzhou-fe/",
  "scopes": ["@yunzhou-fe"]
}

• 当未传参但存在该文件时，脚本将自动读取并生成 .npmrc
• 若传参，脚本会优先使用传入参数，并自动写入更新此配置文件

📁 自动处理的 ignore 文件

如果项目中存在 .gitignore 或 .dockerignore，脚本将自动追加：

.npmrc
.gen-npmrc.config.json

防止将敏感的 token 或配置误提交或打入构建镜像中。

📝 自动生成的 .npmrc 示例

registry=https://registry.npmjs.org/
@yunzhou-fe:registry=https://unicomcdn-npm.pkg.coding.net/cdn-frontend/yunzhou-fe/
always-auth=true
//unicomcdn-npm.pkg.coding.net/cdn-frontend/yunzhou-fe/:_authToken=xxxxxxx

🧪 Docker Buildx 自动检测

• 在 Linux 构建环境中，若未安装 buildx，将自动安装插件
• 插件版本默认安装为 buildx-v0.11.2.linux-amd64
• 推荐使用 Docker 版本：Docker Engine 24.0.2（较新版本可能插件不兼容）

🧠 参数优先级说明

1. 命令行参数（最高优先级）
2. .gen-npmrc.config.json（次选）
3. **本地 **~/.npmrc（仅用于提取认证信息）

💬 常见问题（FAQ）

❓ 为什么 npx yz-npmrc-generator 执行没反应或报错？

• 请确认使用 Bash 环境（macOS、Linux、Git Bash、WSL 均可）
• 使用 CMD 或 PowerShell 运行将导致参数无法识别或脚本未执行