com.jimuwd.xian.registry-proxy 1.0.1 → 1.0.3

package/README.MD

@@ -3,53 +3,56 @@
 
 ## 项目简介
 
-`com.jimuwd.xian.registry-proxy` 是一个轻量级的 npm 代理服务器，旨在为 Node.js 项目提供多 registry 的代理和 fallback 机制。它通过读取 Yarn 的配置文件（`.yarnrc.yml`），将多个 npm registry（如公共 registry、私有仓库等）代理到一个本地端口（默认 `4873`），并支持在本地 token 缺失时从全局配置文件回退获取认证信息。  
+`com.jimuwd.xian.registry-proxy` 是一个轻量级的 npm 代理服务器，旨在为 Node.js 项目提供多 registry 的代理和 fallback 机制。它通过读取独立的配置文件 `.registry-proxy.yml`，将多个 npm registry（如公共 registry、私有仓库等）代理到一个本地端口（默认 `4873`），并支持在 `.registry-proxy.yml` 中 token 缺失时从 Yarn 配置文件（本地 `.yarnrc.yml` 和全局 `~/.yarnrc.yml`）回退获取认证信息。  
 主要功能：
 - **多 registry 代理**：将多个 npm registry 统一代理到本地端口，提供单一访问入口。
 - **Fallback 机制**：按配置顺序尝试多个 registry，直到找到可用包。
-- **灵活的 token 管理**：优先使用本地配置文件中的 `npmAuthToken`，缺失时从全局配置文件读取。
+- **灵活的 token 管理**：优先使用 `.registry-proxy.yml` 中的 `npmAuthToken`，缺失时从 Yarn 配置文件读取。
 - **优雅关闭**：支持通过 SIGTERM 信号优雅停止服务。
 
-这个工具特别适合需要同时访问多个 npm 源（例如公司私有仓库和公共 npm registry）的开发场景，尤其在 CI/CD 或本地开发中，能显著提高依赖安装的稳定性和效率。
+这个工具特别适合需要同时访问多个 npm 源的开发场景，尤其在 CI/CD 或本地开发中，能提高依赖安装的稳定性和效率。
 
 ---
 
 ## 快速上手指南
 
 ### 安装
-在你的业务项目中，将 `com.jimuwd.xian.registry-proxy` 添加为开发依赖。假设你的私有 Yarn 仓库地址为 `https://your-private-registry.example.com/`：
+在你的业务项目中，将 `com.jimuwd.xian.registry-proxy` 添加为开发依赖。假设你的私有 Yarn 仓库地址为 `https://repo.jimuwd.com/jimuwd/~npm/`：
 
 ```bash
-yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-registry.example.com/
+yarn add --dev com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com/jimuwd/~npm/
 ```
 
 ### 配置
-1. **本地 `.yarnrc.yml`**  
-   在业务项目根目录创建或编辑 `.yarnrc.yml`，指定需要代理的 registry 和本地代理地址。对于需要认证的 registry，建议添加 `npmAlwaysAuth: true`：
+1. **代理配置文件 `.registry-proxy.yml`**  
+   在业务项目根目录创建 `.registry-proxy.yml`，指定需要代理的 registry 列表。每个 registry 必须至少是一个空对象 `{}`，否则会导致解析错误：
    ```yaml
-   npmRegistries:
+   registries:
      "http://localhost:4873/":
        npmAuthToken: "local-token" # 可选
      "https://registry.npmjs.org/":
-       # token 可省略，从全局读取
-     "https://your-private-registry.example.com/":
+       {}                          # 无 token 时使用空对象
+     "https://repo.jimuwd.com/jimuwd/~npm/":
        npmAuthToken: "private-token" # 可选
-       npmAlwaysAuth: true          # 强制要求认证
+   ```
 
+2. **本地 `.yarnrc.yml`**  
+   在项目根目录创建或编辑 `.yarnrc.yml`，指定 Yarn 使用本地代理地址：
+   ```yaml
    npmRegistryServer: "http://localhost:4873/"
    unsafeHttpWhitelist:
      - "localhost"
    ```
 
-2. **全局 `~/.yarnrc.yml`（可选）**  
-   如果本地未提供某些 registry 的 token，可以在用户主目录下的 `.yarnrc.yml` 配置回退 token：
+3. **全局 `~/.yarnrc.yml`（可选）**  
+   如果 `.registry-proxy.yml` 未提供某些 registry 的 token，可以在用户主目录下的 `.yarnrc.yml` 配置回退 token：
    ```yaml
    npmRegistries:
      "https://registry.npmjs.org/":
        npmAuthToken: "global-npm-token"
-     "https://your-private-registry.example.com/":
+     "https://repo.jimuwd.com/jimuwd/~npm/":
        npmAuthToken: "global-private-token"
-       npmAlwaysAuth: true
+       npmAlwaysAuth: true          # 可选，控制 Yarn 行为
    ```
 
 ### 使用
@@ -59,7 +62,7 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
    #!/bin/bash
 
    # 启动代理服务器并记录 PID
-   yarn run registry-proxy .yarnrc.yml ~/.yarnrc.yml &
+   yarn run registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml &
    PROXY_PID=$!
 
    # 等待代理服务器启动，最多 10 秒
@@ -94,7 +97,7 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
    ```json
    {
      "scripts": {
-       "start-proxy": "registry-proxy .yarnrc.yml ~/.yarnrc.yml",
+       "start-proxy": "registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml",
        "install": "bash start-proxy.sh"
      }
    }
@@ -134,11 +137,11 @@ com.jimuwd.xian.registry-proxy/
 
 ### 功能实现
 1. **配置加载（`loadRegistries`）**：
-    - **本地配置文件**：从指定路径（默认 `./.yarnrc.yml`）读取 `npmRegistries`，提取 `registryUrl` 和 `npmAuthToken`。
-    - **全局配置文件**：如果本地 token 缺失，从指定路径（默认 `~/.yarnrc.yml`）读取对应 `registryUrl` 的 token。
-    - **安全设计**：本地 token 缺失时回退到全局 token 的设计，是为了避免将敏感的 `npmAuthToken` 写入项目配置文件并提交到代码仓库，从而降低安全隐患。全局配置文件（如 `~/.yarnrc.yml`）通常存储在用户主目录，不会被版本控制系统追踪。
-    - **优先级**：本地 token > 全局 token > 无 token。
-    - **错误处理**：本地配置文件必须存在且包含 `npmRegistries`，否则退出。
+    - **代理配置文件**：从指定路径（默认 `./.registry-proxy.yml`）读取 `registries`，提取 `registryUrl` 和 `npmAuthToken`。
+    - **Yarn 配置文件回退**：如果 `.registry-proxy.yml` 中 token 缺失，依次从本地 `.yarnrc.yml`（默认 `./.yarnrc.yml`）和全局 `~/.yarnrc.yml`（默认 `~/.yarnrc.yml`）读取对应 `registryUrl` 的 `npmAuthToken`。
+    - **安全设计**：将 `registryUrl` 和 token 配置独立于 `.registry-proxy.yml`，避免敏感信息直接写入 Yarn 配置文件并提交到代码仓库。回退到 Yarn 配置的 token（尤其是全局配置）进一步降低安全隐患。
+    - **优先级**：`.registry-proxy.yml` token > 本地 `.yarnrc.yml` token > 全局 `~/.yarnrc.yml` token > 无 token。
+    - **错误处理**：`.registry-proxy.yml` 必须存在且包含 `registries`，否则退出。
 
 2. **代理逻辑**：
     - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认监听 `4873` 端口。
@@ -154,27 +157,42 @@ com.jimuwd.xian.registry-proxy/
 - **模块系统**：`"module": "nodenext"`，兼容 Node.js v20+。
 - **依赖**：
     - `node-fetch@^3.3.2`：发起 HTTP 请求。
-    - `js-yaml@^4.1.0`：解析 `.yarnrc.yml` 文件。
+    - `js-yaml@^4.1.0`：解析 `.registry-proxy.yml` 和 `.yarnrc.yml` 文件。
 - **Node.js 版本**：推荐 v14+，测试于 v20.17.0。
 
 ### CLI 参数
 ```bash
-registry-proxy [localConfigPath] [globalConfigPath] [port]
+registry-proxy [proxyConfigPath] [localYarnConfigPath] [globalYarnConfigPath] [port]
 ```
-- `localConfigPath`：本地 `.yarnrc.yml` 路径，默认 `./.yarnrc.yml`。
-- `globalConfigPath`：全局 `.yarnrc.yml` 路径，默认 `~/.yarnrc.yml`。
+- `proxyConfigPath`：代理配置文件路径，默认 `./.registry-proxy.yml`。
+- `localYarnConfigPath`：本地 Yarn 配置文件路径，默认 `./.yarnrc.yml`。
+- `globalYarnConfigPath`：全局 Yarn 配置文件路径，默认 `~/.yarnrc.yml`。
 - `port`：代理服务器端口，默认 `4873`。
 
 示例：
 ```bash
-yarn run registry-proxy ./custom.yml ~/.custom.yml 54321
+yarn run registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.yml 54321
 ```
 
 ### 配置说明
-- **`npmAlwaysAuth: true`**：
-    - 在 `.yarnrc.yml` 中为需要认证的 registry 添加此配置，表示对该 registry 的所有请求都必须携带 `npmAuthToken`。
-    - **原因**：某些私有 npm 仓库（例如 Nexus 或 Artifactory）要求即使访问公共包，也需要认证。设置 `npmAlwaysAuth: true` 确保代理在转发请求时始终附带 token，避免因缺少认证导致的 401 错误。
-    - 如果不设置此项，Yarn 可能只在下载受限包时发送 token，而对公开包跳过认证，可能导致请求失败。
+- **`.registry-proxy.yml`**：
+    - 使用 `registries` 字段定义代理的 registry 列表，与 Yarn 的 `npmRegistries` 区分。
+    - **格式要求**：每个 `registryUrl` 后必须跟一个对象（至少是 `{}`），否则解析为 `null` 会导致运行时错误。例如：
+      ```yaml
+      registries:
+        "https://repo.jimuwd.com/jimuwd/~npm/": {}  # 正确
+        "https://repo.jimuwd.com/jimuwd/~npm/":     # 错误，会解析为 null
+      ```
+    - 示例：
+      ```yaml
+      registries:
+        "https://repo.jimuwd.com/jimuwd/~npm/":
+          npmAuthToken: "private-token"
+      ```
+    - **注意**：无需配置 `npmAlwaysAuth`，此项仅适用于 Yarn 的 `.yarnrc.yml`，对代理行为无影响。
+- **`.yarnrc.yml`**：
+    - 仅用于设置 `npmRegistryServer` 和回退 token。
+    - 如果需要强制认证，可在回退的 Yarn 配置中添加 `npmAlwaysAuth: true`。
 
 ### 注意事项
 1. **端口冲突**：
@@ -182,12 +200,12 @@ yarn run registry-proxy ./custom.yml ~/.custom.yml 54321
     - 检查端口占用：`lsof -i :4873`。
     - 可通过参数指定其他端口（如 `54321`）。
 2. **配置文件格式**：
-    - 确保 `.yarnrc.yml` 遵循 Yarn 的格式，`npmRegistries` 为必填项。
+    - 确保 `.registry-proxy.yml` 包含 `registries` 字段，`.yarnrc.yml` 包含 `npmRegistryServer`。
 3. **日志**：
     - 当前通过 `console.log` 输出启动信息，可扩展为文件日志。
 4. **安全性**：
     - 代理运行于本地，未开放外部访问，确保 `unsafeHttpWhitelist` 配置正确。
-    - 避免将 token 写入本地 `.yarnrc.yml`，优先使用全局配置或环境变量。
+    - 优先将 token 放入 `.registry-proxy.yml` 或全局 `.yarnrc.yml`，避免提交到代码仓库。
 
 ### 开发与发布
 1. **构建**：
@@ -196,7 +214,31 @@ yarn run registry-proxy ./custom.yml ~/.custom.yml 54321
    ```
 2. **发布到私有仓库**：
    ```bash
-   yarn publish --registry https://your-private-registry.example.com/
+   yarn publish --registry https://repo.jimuwd.com/jimuwd/~npm/
    ```
 
 ---
+
+### 测试流程
+1. **更新 `.registry-proxy.yml`**：
+   ```yaml
+   registries:
+     "https://repo.jimuwd.com/jimuwd/~npm/": {}
+     "https://registry.npmjs.org/": {}
+   ```
+2. **构建并发布**：
+   ```bash
+   cd registry-proxy
+   yarn install
+   yarn build
+   yarn publish --registry https://repo.jimuwd.com/jimuwd/~npm/
+   ```
+3. **更新业务项目**：
+   ```bash
+   cd your-business-project
+   yarn add com.jimuwd.xian.registry-proxy@latest --registry https://repo.jimuwd.com/jimuwd/~npm/
+   ```
+4. **运行**：
+   ```bash
+   bash start-proxy.sh
+   ```

package/dist/index.js

@@ -6,7 +6,6 @@ import fetch from 'node-fetch';
 import { homedir } from 'os';
 import { join } from 'path';
 async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYarnConfigPath = './.yarnrc.yml', globalYarnConfigPath = join(homedir(), '.yarnrc.yml')) {
-    // 读取独立的 .registry-proxy.yml
     let proxyConfig = { registries: {} };
     try {
         const proxyYamlContent = await readFile(proxyConfigPath, 'utf8');
@@ -15,14 +14,13 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
     }
     catch (e) {
         console.error(`Failed to load ${proxyConfigPath}: ${e.message}`);
-        process.exit(1); // 代理配置文件是必须的
+        process.exit(1);
     }
     if (!proxyConfig.registries || !Object.keys(proxyConfig.registries).length) {
         console.error(`No registries found in ${proxyConfigPath}`);
         process.exit(1);
     }
-    // 读取本地 .yarnrc.yml（用于 token 回退）
-    let localYarnConfig = {};
+    let localYarnConfig = { npmRegistries: {} };
     try {
         const localYamlContent = await readFile(localYarnConfigPath, 'utf8');
         localYarnConfig = load(localYamlContent);
@@ -31,8 +29,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
     catch (e) {
         console.warn(`Failed to load ${localYarnConfigPath}: ${e.message}`);
     }
-    // 读取全局 ~/.yarnrc.yml（用于 token 回退）
-    let globalYarnConfig = {};
+    let globalYarnConfig = { npmRegistries: {} };
     try {
         const globalYamlContent = await readFile(globalYarnConfigPath, 'utf8');
         globalYarnConfig = load(globalYamlContent);
@@ -41,16 +38,16 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
     catch (e) {
         console.warn(`Failed to load ${globalYarnConfigPath}: ${e.message}`);
     }
-    // 从 .registry-proxy.yml 获取 registries，并回退读取 token
     const registries = Object.entries(proxyConfig.registries).map(([url, regConfig]) => {
-        let token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
-        // 如果 .registry-proxy.yml 未提供 token，从本地 .yarnrc.yml 回退
-        if (!token && localYarnConfig.npmRegistries && localYarnConfig.npmRegistries[url]) {
+        let token;
+        if (regConfig && 'npmAuthToken' in regConfig) {
+            token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
+        }
+        if (!token && localYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in localYarnConfig.npmRegistries[url]) {
             token = localYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[url].npmAuthToken;
             console.log(`Token for ${url} not found in ${proxyConfigPath}, using local Yarn config`);
         }
-        // 如果本地 .yarnrc.yml 仍无 token，从全局 ~/.yarnrc.yml 回退
-        if (!token && globalYarnConfig.npmRegistries && globalYarnConfig.npmRegistries[url]) {
+        if (!token && globalYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in globalYarnConfig.npmRegistries[url]) {
             token = globalYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || globalYarnConfig.npmRegistries[url].npmAuthToken;
             console.log(`Token for ${url} not found in local Yarn config, using global Yarn config`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.jimuwd.xian.registry-proxy",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "A lightweight npm registry proxy with fallback support",
   "main": "dist/index.js",

package/src/index.ts

@@ -7,11 +7,10 @@ import { homedir } from 'os';
 import { join } from 'path';
 
 interface RegistryConfig { npmAuthToken?: string; }
-interface ProxyConfig { registries: Record<string, RegistryConfig>; }
-interface YarnConfig { npmRegistries?: Record<string, RegistryConfig>; }
+interface ProxyConfig { registries: Record<string, RegistryConfig | null>; }
+interface YarnConfig { npmRegistries?: Record<string, RegistryConfig | null>; }
 
 async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYarnConfigPath = './.yarnrc.yml', globalYarnConfigPath = join(homedir(), '.yarnrc.yml')): Promise<{ url: string; token?: string }[]> {
-    // 读取独立的 .registry-proxy.yml
     let proxyConfig: ProxyConfig = { registries: {} };
     try {
         const proxyYamlContent = await readFile(proxyConfigPath, 'utf8');
@@ -19,7 +18,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
         console.log(`Loaded proxy config from ${proxyConfigPath}`);
     } catch (e) {
         console.error(`Failed to load ${proxyConfigPath}: ${(e as Error).message}`);
-        process.exit(1); // 代理配置文件是必须的
+        process.exit(1);
     }
 
     if (!proxyConfig.registries || !Object.keys(proxyConfig.registries).length) {
@@ -27,8 +26,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
         process.exit(1);
     }
 
-    // 读取本地 .yarnrc.yml（用于 token 回退）
-    let localYarnConfig: YarnConfig = {};
+    let localYarnConfig: YarnConfig = { npmRegistries: {} };
     try {
         const localYamlContent = await readFile(localYarnConfigPath, 'utf8');
         localYarnConfig = load(localYamlContent) as YarnConfig;
@@ -37,8 +35,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
         console.warn(`Failed to load ${localYarnConfigPath}: ${(e as Error).message}`);
     }
 
-    // 读取全局 ~/.yarnrc.yml（用于 token 回退）
-    let globalYarnConfig: YarnConfig = {};
+    let globalYarnConfig: YarnConfig = { npmRegistries: {} };
     try {
         const globalYamlContent = await readFile(globalYarnConfigPath, 'utf8');
         globalYarnConfig = load(globalYamlContent) as YarnConfig;
@@ -47,19 +44,20 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
         console.warn(`Failed to load ${globalYarnConfigPath}: ${(e as Error).message}`);
     }
 
-    // 从 .registry-proxy.yml 获取 registries，并回退读取 token
     const registries = Object.entries(proxyConfig.registries).map(([url, regConfig]) => {
-        let token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
+        let token: string | undefined;
+
+        if (regConfig && 'npmAuthToken' in regConfig) {
+            token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
+        }
 
-        // 如果 .registry-proxy.yml 未提供 token，从本地 .yarnrc.yml 回退
-        if (!token && localYarnConfig.npmRegistries && localYarnConfig.npmRegistries[url]) {
-            token = localYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[url].npmAuthToken;
+        if (!token && localYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in localYarnConfig.npmRegistries[url]) {
+            token = localYarnConfig.npmRegistries[url]!.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[url]!.npmAuthToken;
             console.log(`Token for ${url} not found in ${proxyConfigPath}, using local Yarn config`);
         }
 
-        // 如果本地 .yarnrc.yml 仍无 token，从全局 ~/.yarnrc.yml 回退
-        if (!token && globalYarnConfig.npmRegistries && globalYarnConfig.npmRegistries[url]) {
-            token = globalYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || globalYarnConfig.npmRegistries[url].npmAuthToken;
+        if (!token && globalYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in globalYarnConfig.npmRegistries[url]) {
+            token = globalYarnConfig.npmRegistries[url]!.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || globalYarnConfig.npmRegistries[url]!.npmAuthToken;
             console.log(`Token for ${url} not found in local Yarn config, using global Yarn config`);
         }