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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.MD +60 -72
  2. package/dist/index.js +9 -12
  3. package/package.json +1 -1
  4. package/src/index.ts +14 -16
package/README.MD CHANGED
@@ -17,24 +17,23 @@
17
17
  ## 快速上手指南
18
18
 
19
19
  ### 安装
20
- 在你的业务项目中，将 `com.jimuwd.xian.registry-proxy` 添加为开发依赖。假设你的私有 Yarn 仓库地址为 `https://your-private-registry.example.com/`：
20
+ 在你的业务项目中，将 `com.jimuwd.xian.registry-proxy` 添加为开发依赖。假设你的私有 Yarn 仓库地址为 `https://repo.jimuwd.com/jimuwd/~npm/`：
21
21
 
22
22
  ```bash
23
- yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-registry.example.com/
23
+ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com/jimuwd/~npm/
24
24
  ```
25
25
 
26
26
  ### 配置
27
27
  1. **代理配置文件 `.registry-proxy.yml`**
28
- 在业务项目根目录创建 `.registry-proxy.yml`，指定需要代理的 registry 列表：
28
+ 在业务项目根目录创建 `.registry-proxy.yml`，指定需要代理的 registry 列表。每个 registry 必须至少是一个空对象 `{}`，否则会导致解析错误：
29
29
  ```yaml
30
30
  registries:
31
31
  "http://localhost:4873/":
32
32
  npmAuthToken: "local-token" # 可选
33
33
  "https://registry.npmjs.org/":
34
- # token 可省略，从 Yarn 配置读取
35
- "https://your-private-registry.example.com/":
34
+ {} # 无 token 时使用空对象
35
+ "https://repo.jimuwd.com/jimuwd/~npm/":
36
36
  npmAuthToken: "private-token" # 可选
37
- npmAlwaysAuth: true # 强制要求认证
38
37
  ```
39
38
 
40
39
  2. **本地 `.yarnrc.yml`**
@@ -51,9 +50,9 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
51
50
  npmRegistries:
52
51
  "https://registry.npmjs.org/":
53
52
  npmAuthToken: "global-npm-token"
54
- "https://your-private-registry.example.com/":
53
+ "https://repo.jimuwd.com/jimuwd/~npm/":
55
54
  npmAuthToken: "global-private-token"
56
- npmAlwaysAuth: true
55
+ npmAlwaysAuth: true # 可选，控制 Yarn 行为
57
56
  ```
58
57
 
59
58
  ### 使用
@@ -109,7 +108,7 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
109
108
  ```bash
110
109
  yarn install
111
110
  ```
112
- - 代理会在安装完成后自动停止。
111
+ - 代理会在安装完成后自动停止。
113
112
 
114
113
  ### 输出示例
115
114
  运行后，你会看到类似以下输出：
@@ -138,27 +137,27 @@ com.jimuwd.xian.registry-proxy/
138
137
 
139
138
  ### 功能实现
140
139
  1. **配置加载（`loadRegistries`）**：
141
- - **代理配置文件**：从指定路径（默认 `./.registry-proxy.yml`）读取 `registries`，提取 `registryUrl` 和 `npmAuthToken`。
142
- - **Yarn 配置文件回退**：如果 `.registry-proxy.yml` 中 token 缺失，依次从本地 `.yarnrc.yml`（默认 `./.yarnrc.yml`）和全局 `~/.yarnrc.yml`（默认 `~/.yarnrc.yml`）读取对应 `registryUrl` 的 `npmAuthToken`。
143
- - **安全设计**：将 `registryUrl` 和 token 配置独立于 `.registry-proxy.yml`，避免敏感信息直接写入 Yarn 配置文件并提交到代码仓库。回退到 Yarn 配置的 token（尤其是全局配置）进一步降低安全隐患。
144
- - **优先级**：`.registry-proxy.yml` token > 本地 `.yarnrc.yml` token > 全局 `~/.yarnrc.yml` token > 无 token。
145
- - **错误处理**：`.registry-proxy.yml` 必须存在且包含 `registries`，否则退出。
140
+ - **代理配置文件**：从指定路径（默认 `./.registry-proxy.yml`）读取 `registries`，提取 `registryUrl` 和 `npmAuthToken`。
141
+ - **Yarn 配置文件回退**：如果 `.registry-proxy.yml` 中 token 缺失，依次从本地 `.yarnrc.yml`（默认 `./.yarnrc.yml`）和全局 `~/.yarnrc.yml`（默认 `~/.yarnrc.yml`）读取对应 `registryUrl` 的 `npmAuthToken`。
142
+ - **安全设计**：将 `registryUrl` 和 token 配置独立于 `.registry-proxy.yml`，避免敏感信息直接写入 Yarn 配置文件并提交到代码仓库。回退到 Yarn 配置的 token（尤其是全局配置）进一步降低安全隐患。
143
+ - **优先级**：`.registry-proxy.yml` token > 本地 `.yarnrc.yml` token > 全局 `~/.yarnrc.yml` token > 无 token。
144
+ - **错误处理**：`.registry-proxy.yml` 必须存在且包含 `registries`，否则退出。
146
145
 
147
146
  2. **代理逻辑**：
148
- - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认监听 `4873` 端口。
149
- - **请求转发**：将所有请求按配置顺序转发到目标 registry，附带对应的 `Authorization: Bearer <token>`（如果存在）。
150
- - **Fallback**：依次尝试每个 registry，直到返回成功响应（`response.ok`）或全部失败（返回 404）。
147
+ - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认监听 `4873` 端口。
148
+ - **请求转发**：将所有请求按配置顺序转发到目标 registry，附带对应的 `Authorization: Bearer <token>`（如果存在）。
149
+ - **Fallback**：依次尝试每个 registry，直到返回成功响应（`response.ok`）或全部失败（返回 404）。
151
150
 
152
151
  3. **进程管理**：
153
- - **优雅关闭**：监听 `SIGTERM` 信号，关闭服务器并退出进程。
154
- - **脚本集成**：通过 shell 脚本记录 PID，安装完成后发送 SIGTERM 停止服务。
152
+ - **优雅关闭**：监听 `SIGTERM` 信号，关闭服务器并退出进程。
153
+ - **脚本集成**：通过 shell 脚本记录 PID，安装完成后发送 SIGTERM 停止服务。
155
154
 
156
155
  ### 技术栈
157
156
  - **语言**：TypeScript（ES Modules）。
158
157
  - **模块系统**：`"module": "nodenext"`，兼容 Node.js v20+。
159
158
  - **依赖**：
160
- - `node-fetch@^3.3.2`：发起 HTTP 请求。
161
- - `js-yaml@^4.1.0`：解析 `.registry-proxy.yml` 和 `.yarnrc.yml` 文件。
159
+ - `node-fetch@^3.3.2`：发起 HTTP 请求。
160
+ - `js-yaml@^4.1.0`：解析 `.registry-proxy.yml` 和 `.yarnrc.yml` 文件。
162
161
  - **Node.js 版本**：推荐 v14+，测试于 v20.17.0。
163
162
 
164
163
  ### CLI 参数
@@ -177,32 +176,36 @@ yarn run registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.y
177
176
 
178
177
  ### 配置说明
179
178
  - **`.registry-proxy.yml`**：
180
- - 使用 `registries` 字段定义代理的 registry 列表，与 Yarn 的 `npmRegistries` 区分。
181
- - 示例：
182
- ```yaml
183
- registries:
184
- "https://your-private-registry.example.com/":
185
- npmAuthToken: "private-token"
186
- npmAlwaysAuth: true
187
- ```
188
- - **`npmAlwaysAuth: true`**：
189
- - 在需要认证的 registry 下添加此配置，表示所有请求必须携带 `npmAuthToken`。
190
- - **原因**：某些私有仓库要求即使访问公共包也需要认证，设置此项避免因缺少 token 导致的 401 错误。
191
- - **Yarn 配置**：
192
- - `.yarnrc.yml` 仅用于设置 `npmRegistryServer` 和回退 token，不定义代理的 registry 列表。
179
+ - 使用 `registries` 字段定义代理的 registry 列表，与 Yarn 的 `npmRegistries` 区分。
180
+ - **格式要求**：每个 `registryUrl` 后必须跟一个对象（至少是 `{}`），否则解析为 `null` 会导致运行时错误。例如：
181
+ ```yaml
182
+ registries:
183
+ "https://repo.jimuwd.com/jimuwd/~npm/": {} # 正确
184
+ "https://repo.jimuwd.com/jimuwd/~npm/": # 错误，会解析为 null
185
+ ```
186
+ - 示例：
187
+ ```yaml
188
+ registries:
189
+ "https://repo.jimuwd.com/jimuwd/~npm/":
190
+ npmAuthToken: "private-token"
191
+ ```
192
+ - **注意**：无需配置 `npmAlwaysAuth`，此项仅适用于 Yarn 的 `.yarnrc.yml`，对代理行为无影响。
193
+ - **`.yarnrc.yml`**：
194
+ - 仅用于设置 `npmRegistryServer` 和回退 token。
195
+ - 如果需要强制认证，可在回退的 Yarn 配置中添加 `npmAlwaysAuth: true`。
193
196
 
194
197
  ### 注意事项
195
198
  1. **端口冲突**：
196
- - 默认端口 `4873` 是 Verdaccio 的惯用端口，可能与其他工具冲突。
197
- - 检查端口占用：`lsof -i :4873`。
198
- - 可通过参数指定其他端口（如 `54321`）。
199
+ - 默认端口 `4873` 是 Verdaccio 的惯用端口，可能与其他工具冲突。
200
+ - 检查端口占用：`lsof -i :4873`。
201
+ - 可通过参数指定其他端口（如 `54321`）。
199
202
  2. **配置文件格式**：
200
- - 确保 `.registry-proxy.yml` 包含 `registries` 字段，`.yarnrc.yml` 包含 `npmRegistryServer`。
203
+ - 确保 `.registry-proxy.yml` 包含 `registries` 字段，`.yarnrc.yml` 包含 `npmRegistryServer`。
201
204
  3. **日志**：
202
- - 当前通过 `console.log` 输出启动信息，可扩展为文件日志。
205
+ - 当前通过 `console.log` 输出启动信息，可扩展为文件日志。
203
206
  4. **安全性**：
204
- - 代理运行于本地，未开放外部访问，确保 `unsafeHttpWhitelist` 配置正确。
205
- - 优先将 token 放入 `.registry-proxy.yml` 或全局 `.yarnrc.yml`，避免提交到代码仓库。
207
+ - 代理运行于本地，未开放外部访问，确保 `unsafeHttpWhitelist` 配置正确。
208
+ - 优先将 token 放入 `.registry-proxy.yml` 或全局 `.yarnrc.yml`，避免提交到代码仓库。
206
209
 
207
210
  ### 开发与发布
208
211
  1. **构建**：
@@ -211,46 +214,31 @@ yarn run registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.y
211
214
  ```
212
215
  2. **发布到私有仓库**：
213
216
  ```bash
214
- yarn publish --registry https://your-private-registry.example.com/
217
+ yarn publish --registry https://repo.jimuwd.com/jimuwd/~npm/
215
218
  ```
216
219
 
217
220
  ---
218
221
 
219
222
  ### 测试流程
220
- 1. **构建并发布**：
223
+ 1. **更新 `.registry-proxy.yml`**：
224
+ ```yaml
225
+ registries:
226
+ "https://repo.jimuwd.com/jimuwd/~npm/": {}
227
+ "https://registry.npmjs.org/": {}
228
+ ```
229
+ 2. **构建并发布**：
221
230
  ```bash
222
231
  cd registry-proxy
223
232
  yarn install
224
233
  yarn build
225
- yarn publish --registry https://your-private-registry.example.com/
234
+ yarn publish --registry https://repo.jimuwd.com/jimuwd/~npm/
226
235
  ```
227
- 2. **业务项目配置**：
228
- - `.registry-proxy.yml`：
229
- ```yaml
230
- registries:
231
- "http://localhost:4873/":
232
- npmAuthToken: "local-token"
233
- "https://registry.npmjs.org/":
234
- # 无 token，回退到 Yarn 配置
235
- "https://your-private-registry.example.com/":
236
- npmAuthToken: "private-token"
237
- npmAlwaysAuth: true
238
- ```
239
- - `.yarnrc.yml`：
240
- ```yaml
241
- npmRegistryServer: "http://localhost:4873/"
242
- unsafeHttpWhitelist:
243
- - "localhost"
244
- ```
245
- - `~/.yarnrc.yml`：
246
- ```yaml
247
- npmRegistries:
248
- "https://registry.npmjs.org/":
249
- npmAuthToken: "global-npm-token"
250
- ```
251
- 3. **运行**：
236
+ 3. **更新业务项目**：
252
237
  ```bash
253
- yarn install
238
+ cd your-business-project
239
+ yarn add com.jimuwd.xian.registry-proxy@latest --registry https://repo.jimuwd.com/jimuwd/~npm/
240
+ ```
241
+ 4. **运行**：
242
+ ```bash
243
+ bash start-proxy.sh
254
244
  ```
255
-
256
-
package/dist/index.js CHANGED
@@ -6,7 +6,6 @@ import fetch from 'node-fetch';
6
6
  import { homedir } from 'os';
7
7
  import { join } from 'path';
8
8
  async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYarnConfigPath = './.yarnrc.yml', globalYarnConfigPath = join(homedir(), '.yarnrc.yml')) {
9
- // 读取独立的 .registry-proxy.yml
10
9
  let proxyConfig = { registries: {} };
11
10
  try {
12
11
  const proxyYamlContent = await readFile(proxyConfigPath, 'utf8');
@@ -15,14 +14,13 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
15
14
  }
16
15
  catch (e) {
17
16
  console.error(`Failed to load ${proxyConfigPath}: ${e.message}`);
18
- process.exit(1); // 代理配置文件是必须的
17
+ process.exit(1);
19
18
  }
20
19
  if (!proxyConfig.registries || !Object.keys(proxyConfig.registries).length) {
21
20
  console.error(`No registries found in ${proxyConfigPath}`);
22
21
  process.exit(1);
23
22
  }
24
- // 读取本地 .yarnrc.yml（用于 token 回退）
25
- let localYarnConfig = {};
23
+ let localYarnConfig = { npmRegistries: {} };
26
24
  try {
27
25
  const localYamlContent = await readFile(localYarnConfigPath, 'utf8');
28
26
  localYarnConfig = load(localYamlContent);
@@ -31,8 +29,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
31
29
  catch (e) {
32
30
  console.warn(`Failed to load ${localYarnConfigPath}: ${e.message}`);
33
31
  }
34
- // 读取全局 ~/.yarnrc.yml（用于 token 回退）
35
- let globalYarnConfig = {};
32
+ let globalYarnConfig = { npmRegistries: {} };
36
33
  try {
37
34
  const globalYamlContent = await readFile(globalYarnConfigPath, 'utf8');
38
35
  globalYarnConfig = load(globalYamlContent);
@@ -41,16 +38,16 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
41
38
  catch (e) {
42
39
  console.warn(`Failed to load ${globalYarnConfigPath}: ${e.message}`);
43
40
  }
44
- // 从 .registry-proxy.yml 获取 registries，并回退读取 token
45
41
  const registries = Object.entries(proxyConfig.registries).map(([url, regConfig]) => {
46
- let token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
47
- // 如果 .registry-proxy.yml 未提供 token，从本地 .yarnrc.yml 回退
48
- if (!token && localYarnConfig.npmRegistries && localYarnConfig.npmRegistries[url]) {
42
+ let token;
43
+ if (regConfig && 'npmAuthToken' in regConfig) {
44
+ token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
45
+ }
46
+ if (!token && localYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in localYarnConfig.npmRegistries[url]) {
49
47
  token = localYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[url].npmAuthToken;
50
48
  console.log(`Token for ${url} not found in ${proxyConfigPath}, using local Yarn config`);
51
49
  }
52
- // 如果本地 .yarnrc.yml 仍无 token，从全局 ~/.yarnrc.yml 回退
53
- if (!token && globalYarnConfig.npmRegistries && globalYarnConfig.npmRegistries[url]) {
50
+ if (!token && globalYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in globalYarnConfig.npmRegistries[url]) {
54
51
  token = globalYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || globalYarnConfig.npmRegistries[url].npmAuthToken;
55
52
  console.log(`Token for ${url} not found in local Yarn config, using global Yarn config`);
56
53
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "com.jimuwd.xian.registry-proxy",
3
- "version": "1.0.2",
3
+ "version": "1.0.3",
4
4
  "type": "module",
5
5
  "description": "A lightweight npm registry proxy with fallback support",
6
6
  "main": "dist/index.js",
package/src/index.ts CHANGED
@@ -7,11 +7,10 @@ import { homedir } from 'os';
7
7
  import { join } from 'path';
8
8
 
9
9
  interface RegistryConfig { npmAuthToken?: string; }
10
- interface ProxyConfig { registries: Record<string, RegistryConfig>; }
11
- interface YarnConfig { npmRegistries?: Record<string, RegistryConfig>; }
10
+ interface ProxyConfig { registries: Record<string, RegistryConfig | null>; }
11
+ interface YarnConfig { npmRegistries?: Record<string, RegistryConfig | null>; }
12
12
 
13
13
  async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYarnConfigPath = './.yarnrc.yml', globalYarnConfigPath = join(homedir(), '.yarnrc.yml')): Promise<{ url: string; token?: string }[]> {
14
- // 读取独立的 .registry-proxy.yml
15
14
  let proxyConfig: ProxyConfig = { registries: {} };
16
15
  try {
17
16
  const proxyYamlContent = await readFile(proxyConfigPath, 'utf8');
@@ -19,7 +18,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
19
18
  console.log(`Loaded proxy config from ${proxyConfigPath}`);
20
19
  } catch (e) {
21
20
  console.error(`Failed to load ${proxyConfigPath}: ${(e as Error).message}`);
22
- process.exit(1); // 代理配置文件是必须的
21
+ process.exit(1);
23
22
  }
24
23
 
25
24
  if (!proxyConfig.registries || !Object.keys(proxyConfig.registries).length) {
@@ -27,8 +26,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
27
26
  process.exit(1);
28
27
  }
29
28
 
30
- // 读取本地 .yarnrc.yml（用于 token 回退）
31
- let localYarnConfig: YarnConfig = {};
29
+ let localYarnConfig: YarnConfig = { npmRegistries: {} };
32
30
  try {
33
31
  const localYamlContent = await readFile(localYarnConfigPath, 'utf8');
34
32
  localYarnConfig = load(localYamlContent) as YarnConfig;
@@ -37,8 +35,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
37
35
  console.warn(`Failed to load ${localYarnConfigPath}: ${(e as Error).message}`);
38
36
  }
39
37
 
40
- // 读取全局 ~/.yarnrc.yml（用于 token 回退）
41
- let globalYarnConfig: YarnConfig = {};
38
+ let globalYarnConfig: YarnConfig = { npmRegistries: {} };
42
39
  try {
43
40
  const globalYamlContent = await readFile(globalYarnConfigPath, 'utf8');
44
41
  globalYarnConfig = load(globalYamlContent) as YarnConfig;
@@ -47,19 +44,20 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
47
44
  console.warn(`Failed to load ${globalYarnConfigPath}: ${(e as Error).message}`);
48
45
  }
49
46
 
50
- // 从 .registry-proxy.yml 获取 registries，并回退读取 token
51
47
  const registries = Object.entries(proxyConfig.registries).map(([url, regConfig]) => {
52
- let token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
48
+ let token: string | undefined;
49
+
50
+ if (regConfig && 'npmAuthToken' in regConfig) {
51
+ token = regConfig.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || regConfig.npmAuthToken;
52
+ }
53
53
 
54
- // 如果 .registry-proxy.yml 未提供 token，从本地 .yarnrc.yml 回退
55
- if (!token && localYarnConfig.npmRegistries && localYarnConfig.npmRegistries[url]) {
56
- token = localYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[url].npmAuthToken;
54
+ if (!token && localYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in localYarnConfig.npmRegistries[url]) {
55
+ token = localYarnConfig.npmRegistries[url]!.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[url]!.npmAuthToken;
57
56
  console.log(`Token for ${url} not found in ${proxyConfigPath}, using local Yarn config`);
58
57
  }
59
58
 
60
- // 如果本地 .yarnrc.yml 仍无 token，从全局 ~/.yarnrc.yml 回退
61
- if (!token && globalYarnConfig.npmRegistries && globalYarnConfig.npmRegistries[url]) {
62
- token = globalYarnConfig.npmRegistries[url].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || globalYarnConfig.npmRegistries[url].npmAuthToken;
59
+ if (!token && globalYarnConfig.npmRegistries?.[url] && 'npmAuthToken' in globalYarnConfig.npmRegistries[url]) {
60
+ token = globalYarnConfig.npmRegistries[url]!.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || globalYarnConfig.npmRegistries[url]!.npmAuthToken;
63
61
  console.log(`Token for ${url} not found in local Yarn config, using global Yarn config`);
64
62
  }
65
63