com.jimuwd.xian.registry-proxy 1.0.4 → 1.0.5

package/README.MD

@@ -1,35 +1,26 @@
-
 # README.md
 
 ## 项目简介
 
-`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`）回退获取认证信息。  
+`com.jimuwd.xian.registry-proxy` 是一个轻量级的 npm 代理服务器，旨在为 Node.js 项目提供多 registry 的代理和 fallback 机制。它通过读取独立的配置文件 `.registry-proxy.yml`，将多个 npm registry（如公共 registry、私有仓库等）代理到一个动态分配的本地端口，并在 `.registry-proxy.yml` 中 token 缺失时从 Yarn 配置文件（本地 `.yarnrc.yml` 和全局 `~/.yarnrc.yml`）回退获取认证信息。  
 主要功能：
-- **多 registry 代理**：将多个 npm registry 统一代理到本地端口，提供单一访问入口。
+- **多 registry 代理**：将多个 npm registry 统一代理到本地动态端口，提供单一访问入口。
+- **动态端口**：支持多个项目并行构建，避免端口冲突。
 - **Fallback 机制**：按配置顺序尝试多个 registry，直到找到可用包。
 - **灵活的 token 管理**：优先使用 `.registry-proxy.yml` 中的 `npmAuthToken`，缺失时从 Yarn 配置文件读取。
-- **优雅关闭**：支持通过 SIGTERM 信号优雅停止服务。
+- **优雅关闭**：通过 SIGTERM 信号确保服务彻底停止。
 
-这个工具特别适合需要同时访问多个 npm 源的开发场景，尤其在 CI/CD 或本地开发中，能提高依赖安装的稳定性和效率。
+这个工具特别适合在本地同时构建多个业务项目，尤其在 CI/CD 或开发环境中，能提高依赖安装的效率和灵活性。
 
 ---
 
 ## 快速上手指南
 
-### 安装
-在你的业务项目中，将 `com.jimuwd.xian.registry-proxy` 添加为开发依赖。假设你的私有 Yarn 仓库地址为 `https://repo.jimuwd.com/jimuwd/~npm/`：
-
-```bash
-yarn add --dev com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com/jimuwd/~npm/
-```
-
 ### 配置
 1. **代理配置文件 `.registry-proxy.yml`**  
    在业务项目根目录创建 `.registry-proxy.yml`，指定需要代理的 registry 列表。每个 registry 必须至少是一个空对象 `{}`，否则会导致解析错误：
    ```yaml
    registries:
-     "http://localhost:4873/":
-       npmAuthToken: "local-token" # 可选
      "https://registry.npmjs.org/":
        {}                          # 无 token 时使用空对象
      "https://repo.jimuwd.com/jimuwd/~npm/":
@@ -37,9 +28,8 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com
    ```
 
 2. **本地 `.yarnrc.yml`**  
-   在项目根目录创建或编辑 `.yarnrc.yml`，指定 Yarn 使用本地代理地址：
+   在项目根目录创建或编辑 `.yarnrc.yml`，允许本地代理：
    ```yaml
-   npmRegistryServer: "http://localhost:4873/"
    unsafeHttpWhitelist:
      - "localhost"
    ```
@@ -52,43 +42,47 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com
        npmAuthToken: "global-npm-token"
      "https://repo.jimuwd.com/jimuwd/~npm/":
        npmAuthToken: "global-private-token"
-       npmAlwaysAuth: true          # 可选，控制 Yarn 行为
    ```
 
 ### 使用
-1. **创建启动脚本 `start-proxy.sh`**  
+1. **创建安装脚本 `install-from-proxy-registries.sh`**  
    在项目根目录添加以下脚本，用于启动代理并安装依赖：
    ```bash
    #!/bin/bash
 
-   # 启动代理服务器并记录 PID
-   yarn run registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml &
+   # 通过 npx 运行 registry-proxy，无需预装依赖
+   REGISTRY_PROXY_VERSION=${REGISTRY_PROXY_VERSION:-"latest"}
+   npx com.jimuwd.xian.registry-proxy@"$REGISTRY_PROXY_VERSION" .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml &
    PROXY_PID=$!
 
-   # 等待代理服务器启动，最多 10 秒
-   echo "Waiting for proxy server to start on port 4873..."
+   # 等待代理服务器启动并写入端口，最多 10 秒
+   echo "Waiting for proxy server to start..."
    for i in {1..100}; do
-     if nc -z localhost 4873 2>/dev/null; then
-       echo "Proxy server is ready!"
-       break
+     if [ -f .registry-proxy-port ]; then
+       PROXY_PORT=$(cat .registry-proxy-port)
+       if nc -z localhost "$PROXY_PORT" 2>/dev/null; then
+         echo "Proxy server is ready on port $PROXY_PORT!"
+         break
+       fi
      fi
      sleep 0.1
    done
 
    # 检查是否成功启动
-   if ! nc -z localhost 4873 2>/dev/null; then
-     echo "Error: Proxy server failed to start on port 4873"
+   if [ -z "$PROXY_PORT" ] || ! nc -z localhost "$PROXY_PORT" 2>/dev/null; then
+     echo "Error: Proxy server failed to start"
      kill $PROXY_PID
      exit 1
    fi
 
-   # 使用本地代理运行 yarn install
-   yarn install --registry http://localhost:4873/
+   # 使用动态代理端口运行 yarn install
+   yarn install --registry "http://localhost:$PROXY_PORT/"
 
    # 停止代理服务器
    echo "Stopping proxy server..."
    kill -TERM $PROXY_PID
-   wait $PROXY_PID 2>/dev/null
+   wait $PROXY_PID 2>/dev/null || { echo "Error: Failed to stop proxy server"; exit 1; }
+   rm -f .registry-proxy-port
    echo "Proxy server stopped."
    ```
 
@@ -97,27 +91,32 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com
    ```json
    {
      "scripts": {
-       "start-proxy": "registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml",
-       "install": "bash start-proxy.sh"
+       "install": "bash install-from-proxy-registries.sh"
      }
    }
    ```
 
 3. **运行**  
-   执行以下命令启动代理并安装依赖：
+   在每个项目目录中执行以下命令启动代理并安装依赖：
    ```bash
    yarn install
    ```
-    - 代理会在安装完成后自动停止。
+    - 可选指定版本：
+      ```bash
+      REGISTRY_PROXY_VERSION=1.0.0 yarn install
+      ```
+    - 代理会在安装完成后自动停止，且多个项目可并行运行。
 
 ### 输出示例
-运行后，你会看到类似以下输出：
+运行后，你会看到类似以下输出（端口号会动态变化）：
 ```
-Waiting for proxy server to start on port 4873...
-Proxy server started at http://localhost:4873
-Proxy server is ready!
+Waiting for proxy server to start...
+Proxy server started at http://localhost:49152
+Proxy server is ready on port 49152!
 [yarn install 输出]
 Stopping proxy server...
+Received SIGTERM, shutting down...
+Server closed.
 Proxy server stopped.
 ```
 
@@ -137,21 +136,22 @@ com.jimuwd.xian.registry-proxy/
 
 ### 功能实现
 1. **配置加载（`loadRegistries`）**：
-    - **代理配置文件**：从指定路径（默认 `./.registry-proxy.yml`）读取 `registries`，提取 `registryUrl` 和 `npmAuthToken`。
+    - **代理配置文件**：从指定路径（默认 `./.registry-proxy.yml`）读取 `registries`，支持 `~/` 路径解析。
     - **URL 规范化**：自动去除 `registryUrl` 尾部斜杠，确保 `https://example.com/path/` 和 `https://example.com/path` 被视为同一地址，后配置覆盖前配置。
-    - **Yarn 配置文件回退**：如果 `.registry-proxy.yml` 中 token 缺失，依次从本地 `.yarnrc.yml`（默认 `./.yarnrc.yml`）和全局 `~/.yarnrc.yml`（默认 `~/.yarnrc.yml`）读取对应 `registryUrl` 的 `npmAuthToken`。
-    - **安全设计**：将 `registryUrl` 和 token 配置独立于 `.registry-proxy.yml`，避免敏感信息直接写入 Yarn 配置文件并提交到代码仓库。回退到 Yarn 配置的 token（尤其是全局配置）进一步降低安全隐患。
+    - **Yarn 配置文件回退**：如果 `.registry-proxy.yml` 中 token 缺失，依次从本地 `.yarnrc.yml` 和全局 `~/.yarnrc.yml` 读取对应 `registryUrl` 的 `npmAuthToken`。
+    - **安全设计**：将 `registryUrl` 和 token 配置独立于 `.registry-proxy.yml`，避免敏感信息写入 Yarn 配置文件并提交到代码仓库。
     - **优先级**：`.registry-proxy.yml` token > 本地 `.yarnrc.yml` token > 全局 `~/.yarnrc.yml` token > 无 token。
     - **错误处理**：`.registry-proxy.yml` 必须存在且包含 `registries`，否则退出。
 
 2. **代理逻辑**：
-    - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认监听 `4873` 端口。
+    - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认使用动态端口（`port = 0`）。
+    - **端口分配**：系统自动分配可用端口，并写入 `.registry-proxy-port` 文件。
     - **请求转发**：将所有请求按配置顺序转发到目标 registry，附带对应的 `Authorization: Bearer <token>`（如果存在）。
     - **Fallback**：依次尝试每个 registry，直到返回成功响应（`response.ok`）或全部失败（返回 404）。
 
 3. **进程管理**：
-    - **优雅关闭**：监听 `SIGTERM` 信号，关闭服务器并退出进程。
-    - **脚本集成**：通过 shell 脚本记录 PID，安装完成后发送 SIGTERM 停止服务。
+    - **优雅关闭**：监听 `SIGTERM` 信号，先关闭服务器再退出进程，5 秒超时强制退出。
+    - **脚本集成**：通过 shell 脚本动态运行代理，记录 PID 和端口，安装完成后停止服务。
 
 ### 技术栈
 - **语言**：TypeScript（ES Modules）。
@@ -163,50 +163,41 @@ com.jimuwd.xian.registry-proxy/
 
 ### CLI 参数
 ```bash
-registry-proxy [proxyConfigPath] [localYarnConfigPath] [globalYarnConfigPath] [port]
+npx com.jimuwd.xian.registry-proxy [proxyConfigPath] [localYarnConfigPath] [globalYarnConfigPath] [port]
 ```
 - `proxyConfigPath`：代理配置文件路径，默认 `./.registry-proxy.yml`。
 - `localYarnConfigPath`：本地 Yarn 配置文件路径，默认 `./.yarnrc.yml`。
 - `globalYarnConfigPath`：全局 Yarn 配置文件路径，默认 `~/.yarnrc.yml`。
-- `port`：代理服务器端口，默认 `4873`。
+- `port`：代理服务器端口，默认 `0`（动态分配）。
 
 示例：
 ```bash
-yarn run registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.yml 54321
+npx com.jimuwd.xian.registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.yml
 ```
 
 ### 配置说明
 - **`.registry-proxy.yml`**：
-    - 使用 `registries` 字段定义代理的 registry 列表，与 Yarn 的 `npmRegistries` 区分。
-    - **格式要求**：每个 `registryUrl` 后必须跟一个对象（至少是 `{}`），否则解析为 `null` 会导致运行时错误。例如：
-      ```yaml
-      registries:
-        "https://repo.jimuwd.com/some/project/path/~npm/": {}  # 正确
-        "https://repo.jimuwd.com/some/project/path1/~npm/":     # 错误，会解析为 null
-      ```
+    - 使用 `registries` 字段定义代理的 registry 列表。
+    - **格式要求**：每个 `registryUrl` 后必须跟一个对象（至少是 `{}`），否则解析为 `null` 会导致运行时错误。
     - 示例：
       ```yaml
       registries:
         "https://repo.jimuwd.com/jimuwd/~npm/":
           npmAuthToken: "private-token"
       ```
-    - **注意**：无需配置 `npmAlwaysAuth`，此项仅适用于 Yarn 的 `.yarnrc.yml`，对代理行为无影响。
 - **`.yarnrc.yml`**：
-    - 仅用于设置 `npmRegistryServer` 和回退 token。
-    - 如果需要强制认证，可在回退的 Yarn 配置中添加 `npmAlwaysAuth: true`。
+    - 仅用于设置 `unsafeHttpWhitelist`，代理地址由脚本动态提供。
 
 ### 注意事项
-1. **端口冲突**：
-    - 默认端口 `4873` 是 Verdaccio 的惯用端口，可能与其他工具冲突。
-    - 检查端口占用：`lsof -i :4873`。
-    - 可通过参数指定其他端口（如 `54321`）。
-2. **配置文件格式**：
-    - 确保 `.registry-proxy.yml` 包含 `registries` 字段，`.yarnrc.yml` 包含 `npmRegistryServer`。
-3. **日志**：
-    - 当前通过 `console.log` 输出启动信息，可扩展为文件日志。
-4. **安全性**：
-    - 代理运行于本地，未开放外部访问，确保 `unsafeHttpWhitelist` 配置正确。
-    - 优先将 token 放入 `.registry-proxy.yml` 或全局 `.yarnrc.yml`，避免提交到代码仓库。
+1. **并行构建**：
+    - 每个项目使用独立端口，支持本地多项目同时构建。
+    - 无需预装 `com.jimuwd.xian.registry-proxy`，通过 `npx` 动态运行。
+2. **路径支持**：
+    - 支持 `~/` 路径，如 `~/.yarnrc.yml`。
+3. **日志顺序**：
+    - 停止时先打印 `Received SIGTERM, shutting down...`，然后 `Server closed.`，最后脚本输出 `Proxy server stopped.`。
+4. **优雅退出**：
+    - 确保服务器关闭后进程退出，超时强制终止。
 
 ### 开发与发布
 1. **构建**：
@@ -221,25 +212,13 @@ yarn run registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.y
 ---
 
 ### 测试流程
-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. **运行**：
+1. **准备项目**：
+    - 项目目录包含 `.registry-proxy.yml`、`install-from-proxy-registries.sh` 和 `package.json`。
+2. **运行**：
    ```bash
-   bash start-proxy.sh
+   cd project1 && yarn install &
+   cd project2 && yarn install &
    ```
+3. **验证**：
+    - 检查两个项目使用不同端口。
+    - 确保日志顺序正确，且进程正常退出（`ps aux | grep registry-proxy` 无残留）。

package/dist/index.js

@@ -4,49 +4,54 @@ import { readFile } from 'fs/promises';
 import { load } from 'js-yaml';
 import fetch from 'node-fetch';
 import { homedir } from 'os';
-import { join } from 'path';
-// 规范化 URL，去除尾部斜杠
+import { join, resolve } from 'path';
+import { writeFileSync } from 'fs';
 function normalizeUrl(url) {
     return url.endsWith('/') ? url.slice(0, -1) : url;
 }
+function resolvePath(path) {
+    return path.startsWith('~/') ? join(homedir(), path.slice(2)) : resolve(path);
+}
 async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYarnConfigPath = './.yarnrc.yml', globalYarnConfigPath = join(homedir(), '.yarnrc.yml')) {
+    const resolvedProxyPath = resolvePath(proxyConfigPath);
+    const resolvedLocalYarnPath = resolvePath(localYarnConfigPath);
+    const resolvedGlobalYarnPath = resolvePath(globalYarnConfigPath);
     let proxyConfig = { registries: {} };
     try {
-        const proxyYamlContent = await readFile(proxyConfigPath, 'utf8');
+        const proxyYamlContent = await readFile(resolvedProxyPath, 'utf8');
         proxyConfig = load(proxyYamlContent);
-        console.log(`Loaded proxy config from ${proxyConfigPath}`);
+        console.log(`Loaded proxy config from ${resolvedProxyPath}`);
     }
     catch (e) {
-        console.error(`Failed to load ${proxyConfigPath}: ${e.message}`);
+        console.error(`Failed to load ${resolvedProxyPath}: ${e.message}`);
         process.exit(1);
     }
     if (!proxyConfig.registries || !Object.keys(proxyConfig.registries).length) {
-        console.error(`No registries found in ${proxyConfigPath}`);
+        console.error(`No registries found in ${resolvedProxyPath}`);
         process.exit(1);
     }
     let localYarnConfig = { npmRegistries: {} };
     try {
-        const localYamlContent = await readFile(localYarnConfigPath, 'utf8');
+        const localYamlContent = await readFile(resolvedLocalYarnPath, 'utf8');
         localYarnConfig = load(localYamlContent);
-        console.log(`Loaded local Yarn config from ${localYarnConfigPath}`);
+        console.log(`Loaded local Yarn config from ${resolvedLocalYarnPath}`);
     }
     catch (e) {
-        console.warn(`Failed to load ${localYarnConfigPath}: ${e.message}`);
+        console.warn(`Failed to load ${resolvedLocalYarnPath}: ${e.message}`);
     }
     let globalYarnConfig = { npmRegistries: {} };
     try {
-        const globalYamlContent = await readFile(globalYarnConfigPath, 'utf8');
+        const globalYamlContent = await readFile(resolvedGlobalYarnPath, 'utf8');
         globalYarnConfig = load(globalYamlContent);
-        console.log(`Loaded global Yarn config from ${globalYarnConfigPath}`);
+        console.log(`Loaded global Yarn config from ${resolvedGlobalYarnPath}`);
     }
     catch (e) {
-        console.warn(`Failed to load ${globalYarnConfigPath}: ${e.message}`);
+        console.warn(`Failed to load ${resolvedGlobalYarnPath}: ${e.message}`);
     }
-    // 使用 Map 合并重复的 URL
     const registryMap = new Map();
     for (const [url, regConfig] of Object.entries(proxyConfig.registries)) {
         const normalizedUrl = normalizeUrl(url);
-        registryMap.set(normalizedUrl, regConfig); // 后配置覆盖前配置
+        registryMap.set(normalizedUrl, regConfig);
     }
     const registries = Array.from(registryMap.entries()).map(([url, regConfig]) => {
         let token;
@@ -56,7 +61,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
         const normalizedUrl = normalizeUrl(url);
         if (!token && localYarnConfig.npmRegistries?.[normalizedUrl] && 'npmAuthToken' in localYarnConfig.npmRegistries[normalizedUrl]) {
             token = localYarnConfig.npmRegistries[normalizedUrl].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[normalizedUrl].npmAuthToken;
-            console.log(`Token for ${url} not found in ${proxyConfigPath}, using local Yarn config`);
+            console.log(`Token for ${url} not found in ${resolvedProxyPath}, using local Yarn config`);
         }
         if (!token && globalYarnConfig.npmRegistries?.[normalizedUrl] && 'npmAuthToken' in globalYarnConfig.npmRegistries[normalizedUrl]) {
             token = globalYarnConfig.npmRegistries[normalizedUrl].npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || globalYarnConfig.npmRegistries[normalizedUrl].npmAuthToken;
@@ -67,7 +72,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
     });
     return registries;
 }
-export async function startProxyServer(proxyConfigPath, localYarnConfigPath, globalYarnConfigPath, port = 4873) {
+export async function startProxyServer(proxyConfigPath, localYarnConfigPath, globalYarnConfigPath, port = 0) {
     console.log('Starting proxy server...');
     const registries = await loadRegistries(proxyConfigPath, localYarnConfigPath, globalYarnConfigPath);
     const server = createServer(async (req, res) => {
@@ -105,19 +110,49 @@ export async function startProxyServer(proxyConfigPath, localYarnConfigPath, glo
             res.end('Package not found');
         }
     });
-    server.listen(port, () => console.log(`Proxy server started at http://localhost:${port}`));
-    process.on('SIGTERM', () => {
-        console.log('Received SIGTERM, shutting down...');
-        server.close(() => process.exit(0));
+    return new Promise((resolve, reject) => {
+        server.listen(port, () => {
+            const address = server.address();
+            if (!address) {
+                console.error('Failed to get server address: address is null');
+                reject(new Error('Failed to get server address: address is null'));
+                return;
+            }
+            if (typeof address === 'string') {
+                console.error('Server bound to a path (e.g., Unix socket), which is not supported');
+                reject(new Error('Server bound to a path, expected a TCP port'));
+                return;
+            }
+            // 显式声明 address 为 AddressInfo 类型
+            const addressInfo = address;
+            const actualPort = addressInfo.port;
+            console.log(`Proxy server started at http://localhost:${actualPort}`);
+            writeFileSync('.registry-proxy-port', actualPort.toString(), 'utf8');
+            resolve(server);
+        });
+        process.on('SIGTERM', () => {
+            console.log('Received SIGTERM, shutting down...');
+            server.close((err) => {
+                if (err) {
+                    console.error('Error closing server:', err.message);
+                    process.exit(1);
+                }
+                console.log('Server closed.');
+                process.exit(0);
+            });
+            setTimeout(() => {
+                console.error('Server did not close in time, forcing exit...');
+                process.exit(1);
+            }, 5000);
+        });
     });
-    return server;
 }
 if (import.meta.url === `file://${process.argv[1]}`) {
     const proxyConfigPath = process.argv[2];
     const localYarnConfigPath = process.argv[3];
     const globalYarnConfigPath = process.argv[4];
-    const port = parseInt(process.argv[5], 10) || 4873;
-    console.log(`CLI: proxyConfigPath=${proxyConfigPath || './.registry-proxy.yml'}, localYarnConfigPath=${localYarnConfigPath || './.yarnrc.yml'}, globalYarnConfigPath=${globalYarnConfigPath || join(homedir(), '.yarnrc.yml')}, port=${port}`);
+    const port = parseInt(process.argv[5], 10) || 0;
+    console.log(`CLI: proxyConfigPath=${proxyConfigPath || './.registry-proxy.yml'}, localYarnConfigPath=${localYarnConfigPath || './.yarnrc.yml'}, globalYarnConfigPath=${globalYarnConfigPath || join(homedir(), '.yarnrc.yml')}, port=${port || 'dynamic'}`);
     startProxyServer(proxyConfigPath, localYarnConfigPath, globalYarnConfigPath, port).catch(err => {
         console.error('Startup failed:', err.message);
         process.exit(1);

package/package.json

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

package/src/index.ts

@@ -1,59 +1,67 @@
 #!/usr/bin/env node
 import { createServer, Server } from 'http';
+import { AddressInfo } from 'net';
 import { readFile } from 'fs/promises';
 import { load } from 'js-yaml';
 import fetch, { Response } from 'node-fetch';
 import { homedir } from 'os';
-import { join } from 'path';
+import { join, resolve } from 'path';
+import { writeFileSync } from 'fs';
 
 interface RegistryConfig { npmAuthToken?: string; }
 interface ProxyConfig { registries: Record<string, RegistryConfig | null>; }
 interface YarnConfig { npmRegistries?: Record<string, RegistryConfig | null>; }
 
-// 规范化 URL，去除尾部斜杠
 function normalizeUrl(url: string): string {
     return url.endsWith('/') ? url.slice(0, -1) : url;
 }
 
+function resolvePath(path: string): string {
+    return path.startsWith('~/') ? join(homedir(), path.slice(2)) : resolve(path);
+}
+
 async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYarnConfigPath = './.yarnrc.yml', globalYarnConfigPath = join(homedir(), '.yarnrc.yml')): Promise<{ url: string; token?: string }[]> {
+    const resolvedProxyPath = resolvePath(proxyConfigPath);
+    const resolvedLocalYarnPath = resolvePath(localYarnConfigPath);
+    const resolvedGlobalYarnPath = resolvePath(globalYarnConfigPath);
+
     let proxyConfig: ProxyConfig = { registries: {} };
     try {
-        const proxyYamlContent = await readFile(proxyConfigPath, 'utf8');
+        const proxyYamlContent = await readFile(resolvedProxyPath, 'utf8');
         proxyConfig = load(proxyYamlContent) as ProxyConfig;
-        console.log(`Loaded proxy config from ${proxyConfigPath}`);
+        console.log(`Loaded proxy config from ${resolvedProxyPath}`);
     } catch (e) {
-        console.error(`Failed to load ${proxyConfigPath}: ${(e as Error).message}`);
+        console.error(`Failed to load ${resolvedProxyPath}: ${(e as Error).message}`);
         process.exit(1);
     }
 
     if (!proxyConfig.registries || !Object.keys(proxyConfig.registries).length) {
-        console.error(`No registries found in ${proxyConfigPath}`);
+        console.error(`No registries found in ${resolvedProxyPath}`);
         process.exit(1);
     }
 
     let localYarnConfig: YarnConfig = { npmRegistries: {} };
     try {
-        const localYamlContent = await readFile(localYarnConfigPath, 'utf8');
+        const localYamlContent = await readFile(resolvedLocalYarnPath, 'utf8');
         localYarnConfig = load(localYamlContent) as YarnConfig;
-        console.log(`Loaded local Yarn config from ${localYarnConfigPath}`);
+        console.log(`Loaded local Yarn config from ${resolvedLocalYarnPath}`);
     } catch (e) {
-        console.warn(`Failed to load ${localYarnConfigPath}: ${(e as Error).message}`);
+        console.warn(`Failed to load ${resolvedLocalYarnPath}: ${(e as Error).message}`);
     }
 
     let globalYarnConfig: YarnConfig = { npmRegistries: {} };
     try {
-        const globalYamlContent = await readFile(globalYarnConfigPath, 'utf8');
+        const globalYamlContent = await readFile(resolvedGlobalYarnPath, 'utf8');
         globalYarnConfig = load(globalYamlContent) as YarnConfig;
-        console.log(`Loaded global Yarn config from ${globalYarnConfigPath}`);
+        console.log(`Loaded global Yarn config from ${resolvedGlobalYarnPath}`);
     } catch (e) {
-        console.warn(`Failed to load ${globalYarnConfigPath}: ${(e as Error).message}`);
+        console.warn(`Failed to load ${resolvedGlobalYarnPath}: ${(e as Error).message}`);
     }
 
-    // 使用 Map 合并重复的 URL
     const registryMap = new Map<string, RegistryConfig | null>();
     for (const [url, regConfig] of Object.entries(proxyConfig.registries)) {
         const normalizedUrl = normalizeUrl(url);
-        registryMap.set(normalizedUrl, regConfig); // 后配置覆盖前配置
+        registryMap.set(normalizedUrl, regConfig);
     }
 
     const registries = Array.from(registryMap.entries()).map(([url, regConfig]) => {
@@ -66,7 +74,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
         const normalizedUrl = normalizeUrl(url);
         if (!token && localYarnConfig.npmRegistries?.[normalizedUrl] && 'npmAuthToken' in localYarnConfig.npmRegistries[normalizedUrl]) {
             token = localYarnConfig.npmRegistries[normalizedUrl]!.npmAuthToken?.replace(/\${(.+)}/, (_, key) => process.env[key] || '') || localYarnConfig.npmRegistries[normalizedUrl]!.npmAuthToken;
-            console.log(`Token for ${url} not found in ${proxyConfigPath}, using local Yarn config`);
+            console.log(`Token for ${url} not found in ${resolvedProxyPath}, using local Yarn config`);
         }
 
         if (!token && globalYarnConfig.npmRegistries?.[normalizedUrl] && 'npmAuthToken' in globalYarnConfig.npmRegistries[normalizedUrl]) {
@@ -81,7 +89,7 @@ async function loadRegistries(proxyConfigPath = './.registry-proxy.yml', localYa
     return registries;
 }
 
-export async function startProxyServer(proxyConfigPath?: string, localYarnConfigPath?: string, globalYarnConfigPath?: string, port: number = 4873): Promise<Server> {
+export async function startProxyServer(proxyConfigPath?: string, localYarnConfigPath?: string, globalYarnConfigPath?: string, port: number = 0): Promise<Server> {
     console.log('Starting proxy server...');
     const registries = await loadRegistries(proxyConfigPath, localYarnConfigPath, globalYarnConfigPath);
 
@@ -122,22 +130,54 @@ export async function startProxyServer(proxyConfigPath?: string, localYarnConfig
         }
     });
 
-    server.listen(port, () => console.log(`Proxy server started at http://localhost:${port}`));
+    return new Promise((resolve, reject) => {
+        server.listen(port, () => {
+            const address: AddressInfo | string | null = server.address();
+            if (!address) {
+                console.error('Failed to get server address: address is null');
+                reject(new Error('Failed to get server address: address is null'));
+                return;
+            }
 
-    process.on('SIGTERM', () => {
-        console.log('Received SIGTERM, shutting down...');
-        server.close(() => process.exit(0));
-    });
+            if (typeof address === 'string') {
+                console.error('Server bound to a path (e.g., Unix socket), which is not supported');
+                reject(new Error('Server bound to a path, expected a TCP port'));
+                return;
+            }
 
-    return server;
+            // 显式声明 address 为 AddressInfo 类型
+            const addressInfo: AddressInfo = address;
+            const actualPort: number = addressInfo.port;
+            console.log(`Proxy server started at http://localhost:${actualPort}`);
+            writeFileSync('.registry-proxy-port', actualPort.toString(), 'utf8');
+            resolve(server);
+        });
+
+        process.on('SIGTERM', () => {
+            console.log('Received SIGTERM, shutting down...');
+            server.close((err) => {
+                if (err) {
+                    console.error('Error closing server:', err.message);
+                    process.exit(1);
+                }
+                console.log('Server closed.');
+                process.exit(0);
+            });
+
+            setTimeout(() => {
+                console.error('Server did not close in time, forcing exit...');
+                process.exit(1);
+            }, 5000);
+        });
+    });
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
     const proxyConfigPath = process.argv[2];
     const localYarnConfigPath = process.argv[3];
     const globalYarnConfigPath = process.argv[4];
-    const port = parseInt(process.argv[5], 10) || 4873;
-    console.log(`CLI: proxyConfigPath=${proxyConfigPath || './.registry-proxy.yml'}, localYarnConfigPath=${localYarnConfigPath || './.yarnrc.yml'}, globalYarnConfigPath=${globalYarnConfigPath || join(homedir(), '.yarnrc.yml')}, port=${port}`);
+    const port = parseInt(process.argv[5], 10) || 0;
+    console.log(`CLI: proxyConfigPath=${proxyConfigPath || './.registry-proxy.yml'}, localYarnConfigPath=${localYarnConfigPath || './.yarnrc.yml'}, globalYarnConfigPath=${globalYarnConfigPath || join(homedir(), '.yarnrc.yml')}, port=${port || 'dynamic'}`);
     startProxyServer(proxyConfigPath, localYarnConfigPath, globalYarnConfigPath, port).catch(err => {
         console.error('Startup failed:', (err as Error).message);
         process.exit(1);