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

package/README.MD

@@ -1,245 +1,732 @@
+# Registry Proxy
 
-# 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`）回退获取认证信息。  
-主要功能：
-- **多 registry 代理**：将多个 npm registry 统一代理到本地端口，提供单一访问入口。
-- **Fallback 机制**：按配置顺序尝试多个 registry，直到找到可用包。
-- **灵活的 token 管理**：优先使用 `.registry-proxy.yml` 中的 `npmAuthToken`，缺失时从 Yarn 配置文件读取。
-- **优雅关闭**：支持通过 SIGTERM 信号优雅停止服务。
-
-这个工具特别适合需要同时访问多个 npm 源的开发场景，尤其在 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/":
-       npmAuthToken: "private-token" # 可选
-   ```
-
-2. **本地 `.yarnrc.yml`**  
-   在项目根目录创建或编辑 `.yarnrc.yml`，指定 Yarn 使用本地代理地址：
-   ```yaml
-   npmRegistryServer: "http://localhost:4873/"
-   unsafeHttpWhitelist:
-     - "localhost"
-   ```
-
-3. **全局 `~/.yarnrc.yml`（可选）**  
-   如果 `.registry-proxy.yml` 未提供某些 registry 的 token，可以在用户主目录下的 `.yarnrc.yml` 配置回退 token：
-   ```yaml
-   npmRegistries:
-     "https://registry.npmjs.org/":
-       npmAuthToken: "global-npm-token"
-     "https://repo.jimuwd.com/jimuwd/~npm/":
-       npmAuthToken: "global-private-token"
-       npmAlwaysAuth: true          # 可选，控制 Yarn 行为
-   ```
-
-### 使用
-1. **创建启动脚本 `start-proxy.sh`**  
-   在项目根目录添加以下脚本，用于启动代理并安装依赖：
-   ```bash
-   #!/bin/bash
-
-   # 启动代理服务器并记录 PID
-   yarn run registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml &
-   PROXY_PID=$!
-
-   # 等待代理服务器启动，最多 10 秒
-   echo "Waiting for proxy server to start on port 4873..."
-   for i in {1..100}; do
-     if nc -z localhost 4873 2>/dev/null; then
-       echo "Proxy server is ready!"
-       break
-     fi
-     sleep 0.1
-   done
-
-   # 检查是否成功启动
-   if ! nc -z localhost 4873 2>/dev/null; then
-     echo "Error: Proxy server failed to start on port 4873"
-     kill $PROXY_PID
-     exit 1
-   fi
-
-   # 使用本地代理运行 yarn install
-   yarn install --registry http://localhost:4873/
-
-   # 停止代理服务器
-   echo "Stopping proxy server..."
-   kill -TERM $PROXY_PID
-   wait $PROXY_PID 2>/dev/null
-   echo "Proxy server stopped."
-   ```
-
-2. **添加 Yarn 脚本**  
-   在 `package.json` 中定义快捷命令：
-   ```json
-   {
-     "scripts": {
-       "start-proxy": "registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml",
-       "install": "bash start-proxy.sh"
-     }
-   }
-   ```
-
-3. **运行**  
-   执行以下命令启动代理并安装依赖：
-   ```bash
-   yarn install
-   ```
-    - 代理会在安装完成后自动停止。
-
-### 输出示例
-运行后，你会看到类似以下输出：
-```
-Waiting for proxy server to start on port 4873...
-Proxy server started at http://localhost:4873
-Proxy server is ready!
+一个轻量级的 Yarn 代理服务器，支持从多个注册表获取包，并支持身份验证。
+
+[Switch to English README](#english-version)
+
+## 概述
+
+本项目提供了一个代理服务器（`registry-proxy`），允许 Yarn 从多个注册表获取包，并支持身份验证令牌。项目还包括一个脚本（`scripts/install-from-proxy-registries.sh`），用于自动化启动代理服务器、安装依赖和清理资源的过程。该设置确保与 Yarn 无缝集成，开发者只需使用标准的 `yarn` 命令即可通过代理安装依赖。
+
+## 功能
+
+- **多注册表支持**：从多个注册表（例如私有和公共注册表）获取包。
+- **身份验证**：支持 `npmAuthToken` 用于认证注册表，可从 `.registry-proxy.yml`、`.yarnrc.yml` 或环境变量中解析令牌。
+- **动态端口分配**：代理服务器使用动态端口（默认 `0`），确保多个项目可以并行运行而不会发生端口冲突。
+- **无缝 Yarn 集成**：运行 `yarn` 时自动启动代理服务器，安装依赖后停止代理。
+- **健壮的错误处理**：使用严格的 Bash 模式（`set -e`、`set -u`、`set -o pipefail`）确保脚本在发生错误时快速失败。
+- **文件放置控制**：确保临时文件（`.registry-proxy-install.lock` 和 `.registry-proxy-port`）始终放置在项目根目录。
+
+## 前置条件
+
+- **Node.js**：版本 14 或更高。
+- **Yarn**：版本 1.x 或 2.x。
+- **netcat (`nc`)**：用于脚本中的端口可用性检查。安装方法：
+  - macOS：`brew install netcat`
+  - Ubuntu：`sudo apt-get install netcat`
+- **Bash**：安装脚本需要 Bash 兼容的 shell。
+
+## 设置
+
+### 1. 安装 `registry-proxy`
+
+代理服务器已发布到您的私有注册表。可以将其作为依赖安装，或使用 `npx` 直接运行。
+
+```bash
+yarn add com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com/jimuwd/~npm/
+```
+
+或者，安装脚本使用 `npx` 运行代理服务器，因此无需显式安装。
+
+### 2. 配置注册表
+
+在项目根目录创建 `.registry-proxy.yml` 文件，定义注册表：
+
+```yaml
+registries:
+  "https://repo.jimuwd.com/jimuwd/~npm/": {}
+  "https://registry.npmjs.org/": {}
+```
+
+- 对于需要认证的注册表，可以指定 `npmAuthToken`：
+  ```yaml
+  registries:
+    "https://repo.jimuwd.com/jimuwd/~npm/":
+      npmAuthToken: "your-token-here"
+    "https://registry.npmjs.org/": {}
+  ```
+- 令牌也可以从 `.yarnrc.yml`（本地或全局）或环境变量中获取。
+
+### 3. 配置 Yarn
+
+在项目根目录创建 `.yarnrc.yml` 文件，允许 Yarn 使用本地代理：
+
+```yaml
+unsafeHttpWhitelist:
+  - "localhost"
+```
+
+### 4. 创建安装脚本
+
+在 `scripts/` 目录下创建 `install-from-proxy-registries.sh` 脚本，用于自动化代理设置和依赖安装：
+
+```bash
+#!/bin/bash
+
+# 启用严格模式
+set -e  # 命令失败时退出
+set -u  # 未定义变量时退出
+set -o pipefail  # 管道中任一命令失败时退出
+
+# 动态确定项目根目录（假设 package.json 所在目录为根目录）
+find_project_root() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/package.json" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "Error: Could not find project root (package.json not found)" >&2
+  exit 1
+}
+
+PROJECT_ROOT=$(find_project_root)
+
+# 定义锁文件和端口文件路径（固定在项目根目录）
+LOCK_FILE="$PROJECT_ROOT/.registry-proxy-install.lock"
+PORT_FILE="$PROJECT_ROOT/.registry-proxy-port"
+
+# 捕获 Ctrl+C 信号，清理锁文件和端口文件
+cleanup() {
+  echo "Caught interrupt signal, cleaning up..."
+  rm -f "$LOCK_FILE"
+  if [ -n "${PROXY_PID:-}" ]; then
+    echo "Stopping proxy server..."
+    kill -TERM "$PROXY_PID" 2>/dev/null
+    wait "$PROXY_PID" 2>/dev/null || { echo "Error: Failed to stop proxy server"; exit 1; }
+    rm -f "$PORT_FILE"
+    echo "Proxy server stopped."
+  fi
+  exit 1
+}
+
+# 注册信号处理
+trap cleanup SIGINT SIGTERM
+
+# 检查是否已经在运行（通过锁文件）
+if [ -f "$LOCK_FILE" ]; then
+  echo "Custom install script is already running, skipping to avoid loop."
+  exit 0
+fi
+
+# 创建锁文件
+touch "$LOCK_FILE"
+
+# 通过 npx 运行 registry-proxy，无需预装依赖
+# 传递项目根目录作为环境变量，供 registry-proxy 使用
+REGISTRY_PROXY_VERSION="${REGISTRY_PROXY_VERSION:-latest}"  # 默认使用 latest，可通过环境变量指定
+PROJECT_ROOT="$PROJECT_ROOT" 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..."
+for i in {1..100}; do
+  if [ -f "$PORT_FILE" ]; then
+    PROXY_PORT=$(cat "$PORT_FILE")
+    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 [ -z "${PROXY_PORT:-}" ] || ! nc -z localhost "$PROXY_PORT" 2>/dev/null; then
+  echo "Error: Proxy server failed to start"
+  kill "$PROXY_PID" 2>/dev/null || true  # 忽略 kill 失败
+  rm -f "$LOCK_FILE"
+  exit 1
+fi
+
+# 使用动态代理端口运行 yarn install
+# 切换到项目根目录运行 yarn install，确保 yarn 行为一致
+cd "$PROJECT_ROOT"
+yarn install --registry "http://localhost:$PROXY_PORT/"
+
+# 停止代理服务器
+echo "Stopping proxy server..."
+kill -TERM "$PROXY_PID"
+wait "$PROXY_PID" 2>/dev/null || { echo "Error: Failed to stop proxy server"; rm -f "$LOCK_FILE"; exit 1; }
+rm -f "$PORT_FILE"  # 清理临时文件
+echo "Proxy server stopped."
+
+# 清理锁文件
+rm -f "$LOCK_FILE"
+```
+
+### 5. 设置脚本权限
+
+确保脚本具有可执行权限，并将权限状态提交到版本控制：
+
+```bash
+chmod +x scripts/install-from-proxy-registries.sh
+git add scripts/install-from-proxy-registries.sh
+git commit -m "Add install script with executable permission"
+```
+
+### 6. 与 Yarn 集成
+
+更新 `package.json`，使 `yarn` 命令自动运行脚本：
+
+```json
+{
+  "scripts": {
+    "preinstall": "bash scripts/install-from-proxy-registries.sh",
+    "install": "echo 'Custom install script is running via preinstall, skipping default install.'"
+  }
+}
+```
+
+- **`preinstall`**：在 Yarn 默认安装过程之前运行脚本。
+- **`install`**：跳过 Yarn 默认安装行为，因为脚本已处理依赖安装。
+
+## 使用方法
+
+### 安装依赖
+
+只需运行标准的 `yarn` 命令即可通过代理安装依赖：
+
+```bash
+yarn
+```
+
+- 脚本将：
+   1. 在动态端口上启动代理服务器。
+   2. 使用代理安装依赖。
+   3. 停止代理服务器并清理临时文件。
+
+- 指定 `registry-proxy` 版本：
+  ```bash
+  REGISTRY_PROXY_VERSION=1.0.0 yarn
+  ```
+
+### 示例输出
+
+```
+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.
+Custom install script is running via preinstall, skipping default install.
 ```
 
----
-
-## 技术说明
-
-### 项目结构
-```
-com.jimuwd.xian.registry-proxy/
-├── src/
-│   └── index.ts       # 主逻辑：代理服务器实现
-├── package.json       # 项目配置和依赖
-├── tsconfig.json      # TypeScript 配置
-└── dist/              # 编译后的输出目录
-```
-
-### 功能实现
-1. **配置加载（`loadRegistries`）**：
-    - **代理配置文件**：从指定路径（默认 `./.registry-proxy.yml`）读取 `registries`，提取 `registryUrl` 和 `npmAuthToken`。
-    - **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（尤其是全局配置）进一步降低安全隐患。
-    - **优先级**：`.registry-proxy.yml` token > 本地 `.yarnrc.yml` token > 全局 `~/.yarnrc.yml` token > 无 token。
-    - **错误处理**：`.registry-proxy.yml` 必须存在且包含 `registries`，否则退出。
-
-2. **代理逻辑**：
-    - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认监听 `4873` 端口。
-    - **请求转发**：将所有请求按配置顺序转发到目标 registry，附带对应的 `Authorization: Bearer <token>`（如果存在）。
-    - **Fallback**：依次尝试每个 registry，直到返回成功响应（`response.ok`）或全部失败（返回 404）。
-
-3. **进程管理**：
-    - **优雅关闭**：监听 `SIGTERM` 信号，关闭服务器并退出进程。
-    - **脚本集成**：通过 shell 脚本记录 PID，安装完成后发送 SIGTERM 停止服务。
-
-### 技术栈
-- **语言**：TypeScript（ES Modules）。
-- **模块系统**：`"module": "nodenext"`，兼容 Node.js v20+。
-- **依赖**：
-    - `node-fetch@^3.3.2`：发起 HTTP 请求。
-    - `js-yaml@^4.1.0`：解析 `.registry-proxy.yml` 和 `.yarnrc.yml` 文件。
-- **Node.js 版本**：推荐 v14+，测试于 v20.17.0。
-
-### CLI 参数
-```bash
-registry-proxy [proxyConfigPath] [localYarnConfigPath] [globalYarnConfigPath] [port]
-```
-- `proxyConfigPath`：代理配置文件路径，默认 `./.registry-proxy.yml`。
-- `localYarnConfigPath`：本地 Yarn 配置文件路径，默认 `./.yarnrc.yml`。
-- `globalYarnConfigPath`：全局 Yarn 配置文件路径，默认 `~/.yarnrc.yml`。
-- `port`：代理服务器端口，默认 `4873`。
-
-示例：
-```bash
-yarn run registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.yml 54321
-```
-
-### 配置说明
-- **`.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
-      ```
-    - 示例：
-      ```yaml
-      registries:
-        "https://repo.jimuwd.com/jimuwd/~npm/":
-          npmAuthToken: "private-token"
-      ```
-    - **注意**：无需配置 `npmAlwaysAuth`，此项仅适用于 Yarn 的 `.yarnrc.yml`，对代理行为无影响。
-- **`.yarnrc.yml`**：
-    - 仅用于设置 `npmRegistryServer` 和回退 token。
-    - 如果需要强制认证，可在回退的 Yarn 配置中添加 `npmAlwaysAuth: true`。
-
-### 注意事项
-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. **构建**：
-   ```bash
-   yarn build
-   ```
-2. **发布到私有仓库**：
-   ```bash
-   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
-   ```
+### 并行构建
+
+代理服务器使用动态端口，因此可以并行运行多个项目：
+
+```bash
+cd project1 && yarn &
+cd project2 && yarn &
+```
+
+每个项目将使用不同的端口（例如 `49152` 和 `49153`）。
+
+## 临时文件
+
+脚本在执行期间会生成两个临时文件：
+
+- **`.registry-proxy-install.lock`**：
+   - 用途：防止脚本在同一项目中多次运行（避免 `yarn install` 导致的循环）。
+   - 位置：始终放置在项目根目录（`package.json` 所在目录）。
+- **`.registry-proxy-port`**：
+   - 用途：存储代理服务器的动态端口号。
+   - 位置：始终放置在项目根目录。
+
+### 防止文件误放置
+
+- 脚本通过查找 `package.json` 动态确定项目根目录，确保临时文件始终放置在正确位置，即使从子目录运行 `yarn`（例如 `cd src && yarn`）。
+- 如果无法找到项目根目录，脚本将报错并退出：
+  ```
+  Error: Could not find project root (package.json not found)
+  ```
+
+### 清理
+
+- 临时文件会在以下情况下自动删除：
+   - 脚本成功完成时。
+   - 中断（例如 `Ctrl+C`）时。
+- 脚本使用信号处理（`trap`）确保即使中断也能执行清理。
+
+## 注意事项
+
+1. **严格模式**：
+   - 脚本使用 Bash 严格模式（`set -e`、`set -u`、`set -o pipefail`）确保健壮的错误处理：
+      - `set -e`：任何命令失败时退出。
+      - `set -u`：未定义变量时退出。
+      - `set -o pipefail`：管道中任一命令失败时退出。
+
+2. **并行执行**：
+   - 锁文件（`.registry-proxy-install.lock`）仅在同一项目内防止重复执行，不影响不同项目的并行构建。
+   - 如果需要在同一项目中运行多个 `yarn` 进程（例如 CI 环境），可以考虑为每个进程使用唯一的锁文件（例如基于进程 ID）。
+
+3. **依赖**：
+   - 确保已安装 `nc`（netcat）以进行端口可用性检查。
+   - 脚本使用 `npx` 运行 `registry-proxy`，无需预安装。
+
+## 故障排除
+
+### 代理服务器无法启动
+
+- **症状**：`Error: Proxy server failed to start`
+- **可能原因**：
+   - 指定的 `REGISTRY_PROXY_VERSION` 无效。
+   - 网络问题导致 `npx` 无法下载包。
+- **解决方法**：
+   - 验证版本：`REGISTRY_PROXY_VERSION=latest yarn`。
+   - 检查网络连接并重试。
+
+### 临时文件未清理
+
+- **症状**：`.registry-proxy-install.lock` 或 `.registry-proxy-port` 在脚本执行后仍存在。
+- **可能原因**：脚本被异常终止（例如 `kill -9` 而非 `Ctrl+C`）。
+- **解决方法**：
+   - 手动删除文件：
+     ```bash
+     rm -f .registry-proxy-install.lock .registry-proxy-port
+     ```
+   - 使用 `Ctrl+C` 或 `kill -TERM` 确保正常清理。
+
+### Yarn 安装失败
+
+- **症状**：`yarn install` 失败并显示网络错误。
+- **可能原因**：代理服务器未正确启动，或注册表不可达。
+- **解决方法**：
+   - 检查代理服务器日志（由 `registry-proxy` 输出）。
+   - 验证 `.registry-proxy.yml` 中的注册表 URL。
+
+## 测试
+
+### 正常安装
+
+```bash
+cd project1
+yarn
+```
+
+### 子目录安装
+
+从子目录运行 `yarn`，验证临时文件是否放置在项目根目录：
+
+```bash
+cd project1/src
+yarn
+ls ../.registry-proxy-install.lock ../.registry-proxy-port
+```
+
+### 中断处理
+
+运行 `yarn` 并在执行期间按 `Ctrl+C`，验证清理：
+
+```bash
+cd project1
+yarn
+# 在 "Waiting for proxy server to start..." 后按 Ctrl+C
+ls .registry-proxy-install.lock .registry-proxy-port
+```
+
+预期输出：文件应不存在。
+
+### 并行构建
+
+并行运行多个项目，验证端口分配：
+
+```bash
+cd project1 && yarn &
+cd project2 && yarn &
+```
+
+## 贡献
+
+1. Fork 本仓库。
+2. 创建功能分支：`git checkout -b feature-name`。
+3. 提交更改：`git commit -m "Add feature"`。
+4. 推送分支：`git push origin feature-name`。
+5. 提交 Pull Request。
+
+## 许可证
+
+MIT 许可证。详见 [LICENSE](LICENSE)。
+
+
+# English Version
+
+## Registry Proxy
+
+A lightweight proxy server for Yarn to fetch packages from multiple registries with authentication support.
+
+## Overview
+
+This project provides a proxy server (`registry-proxy`) that allows Yarn to fetch packages from multiple registries, with support for authentication tokens. It also includes a script (`scripts/install-from-proxy-registries.sh`) to automate the process of starting the proxy server, installing dependencies, and cleaning up resources. The setup ensures seamless integration with Yarn, allowing developers to use the standard `yarn` command to install dependencies via the proxy.
+
+## Features
+
+- **Multi-Registry Support**: Fetch packages from multiple registries (e.g., private and public registries).
+- **Authentication**: Supports `npmAuthToken` for authenticated registries, with token resolution from `.registry-proxy.yml`, `.yarnrc.yml`, or environment variables.
+- **Dynamic Port Allocation**: The proxy server uses a dynamic port (default `0`), ensuring multiple projects can run in parallel without port conflicts.
+- **Seamless Yarn Integration**: Automatically starts the proxy server when running `yarn`, installs dependencies, and stops the proxy afterward.
+- **Robust Error Handling**: Uses strict Bash modes (`set -e`, `set -u`, `set -o pipefail`) to ensure the script fails fast on errors.
+- **File Placement Control**: Ensures temporary files (`.registry-proxy-install.lock` and `.registry-proxy-port`) are always placed in the project root directory.
+
+## Prerequisites
+
+- **Node.js**: Version 14 or higher.
+- **Yarn**: Version 1.x or 2.x.
+- **netcat (`nc`)**: Required for port availability checks in the install script. Install via:
+   - On macOS: `brew install netcat`
+   - On Ubuntu: `sudo apt-get install netcat`
+- **Bash**: The install script requires a Bash-compatible shell.
+
+## Setup
+
+### 1. Install `registry-proxy`
+
+The proxy server is published to your private registry. Install it as a dependency or use `npx` to run it directly.
+
+```bash
+yarn add com.jimuwd.xian.registry-proxy --registry https://repo.jimuwd.com/jimuwd/~npm/
+```
+
+Alternatively, the install script uses `npx` to run the proxy server, so you don't need to install it explicitly.
+
+### 2. Configure Registries
+
+Create a `.registry-proxy.yml` file in your project root to define the registries:
+
+```yaml
+registries:
+  "https://repo.jimuwd.com/jimuwd/~npm/": {}
+  "https://registry.npmjs.org/": {}
+```
+
+- You can specify `npmAuthToken` for authenticated registries:
+  ```yaml
+  registries:
+    "https://repo.jimuwd.com/jimuwd/~npm/":
+      npmAuthToken: "your-token-here"
+    "https://registry.npmjs.org/": {}
+  ```
+- Tokens can also be sourced from `.yarnrc.yml` (local or global) or environment variables.
+
+### 3. Configure Yarn
+
+Create a `.yarnrc.yml` file in your project root to allow Yarn to use the local proxy:
+
+```yaml
+unsafeHttpWhitelist:
+  - "localhost"
+```
+
+### 4. Create the Install Script
+
+Create a script at `scripts/install-from-proxy-registries.sh` to automate the proxy setup and dependency installation:
+
+```bash
+#!/bin/bash
+
+# 启用严格模式
+set -e  # 命令失败时退出
+set -u  # 未定义变量时退出
+set -o pipefail  # 管道中任一命令失败时退出
+
+# 动态确定项目根目录（假设 package.json 所在目录为根目录）
+find_project_root() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/package.json" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "Error: Could not find project root (package.json not found)" >&2
+  exit 1
+}
+
+PROJECT_ROOT=$(find_project_root)
+
+# 定义锁文件和端口文件路径（固定在项目根目录）
+LOCK_FILE="$PROJECT_ROOT/.registry-proxy-install.lock"
+PORT_FILE="$PROJECT_ROOT/.registry-proxy-port"
+
+# 捕获 Ctrl+C 信号，清理锁文件和端口文件
+cleanup() {
+  echo "Caught interrupt signal, cleaning up..."
+  rm -f "$LOCK_FILE"
+  if [ -n "${PROXY_PID:-}" ]; then
+    echo "Stopping proxy server..."
+    kill -TERM "$PROXY_PID" 2>/dev/null
+    wait "$PROXY_PID" 2>/dev/null || { echo "Error: Failed to stop proxy server"; exit 1; }
+    rm -f "$PORT_FILE"
+    echo "Proxy server stopped."
+  fi
+  exit 1
+}
+
+# 注册信号处理
+trap cleanup SIGINT SIGTERM
+
+# 检查是否已经在运行（通过锁文件）
+if [ -f "$LOCK_FILE" ]; then
+  echo "Custom install script is already running, skipping to avoid loop."
+  exit 0
+fi
+
+# 创建锁文件
+touch "$LOCK_FILE"
+
+# 通过 npx 运行 registry-proxy，无需预装依赖
+# 传递项目根目录作为环境变量，供 registry-proxy 使用
+REGISTRY_PROXY_VERSION="${REGISTRY_PROXY_VERSION:-latest}"  # 默认使用 latest，可通过环境变量指定
+PROJECT_ROOT="$PROJECT_ROOT" 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..."
+for i in {1..100}; do
+  if [ -f "$PORT_FILE" ]; then
+    PROXY_PORT=$(cat "$PORT_FILE")
+    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 [ -z "${PROXY_PORT:-}" ] || ! nc -z localhost "$PROXY_PORT" 2>/dev/null; then
+  echo "Error: Proxy server failed to start"
+  kill "$PROXY_PID" 2>/dev/null || true  # 忽略 kill 失败
+  rm -f "$LOCK_FILE"
+  exit 1
+fi
+
+# 使用动态代理端口运行 yarn install
+# 切换到项目根目录运行 yarn install，确保 yarn 行为一致
+cd "$PROJECT_ROOT"
+yarn install --registry "http://localhost:$PROXY_PORT/"
+
+# 停止代理服务器
+echo "Stopping proxy server..."
+kill -TERM "$PROXY_PID"
+wait "$PROXY_PID" 2>/dev/null || { echo "Error: Failed to stop proxy server"; rm -f "$LOCK_FILE"; exit 1; }
+rm -f "$PORT_FILE"  # 清理临时文件
+echo "Proxy server stopped."
+
+# 清理锁文件
+rm -f "$LOCK_FILE"
+```
+
+### 5. Set Script Permissions
+
+Ensure the script is executable and commit the permission to version control:
+
+```bash
+chmod +x scripts/install-from-proxy-registries.sh
+git add scripts/install-from-proxy-registries.sh
+git commit -m "Add install script with executable permission"
+```
+
+### 6. Integrate with Yarn
+
+Update your `package.json` to run the script automatically when `yarn` is executed:
+
+```json
+{
+  "scripts": {
+    "preinstall": "bash scripts/install-from-proxy-registries.sh",
+    "install": "echo 'Custom install script is running via preinstall, skipping default install.'"
+  }
+}
+```
+
+- **`preinstall`**: Runs the script before Yarn's default install process.
+- **`install`**: Skips Yarn's default install behavior, as the script already handles dependency installation.
+
+## Usage
+
+### Install Dependencies
+
+Simply run the standard `yarn` command to install dependencies via the proxy:
+
+```bash
+yarn
+```
+
+- The script will:
+   1. Start the proxy server on a dynamic port.
+   2. Install dependencies using the proxy.
+   3. Stop the proxy server and clean up temporary files.
+
+- To specify a version of `registry-proxy`:
+  ```bash
+  REGISTRY_PROXY_VERSION=1.0.0 yarn
+  ```
+
+### Example Output
+
+```
+Waiting for proxy server to start...
+Proxy server started at http://localhost:49152
+Proxy server is ready on port 49152!
+[yarn install output]
+Stopping proxy server...
+Received SIGTERM, shutting down...
+Server closed.
+Proxy server stopped.
+Custom install script is running via preinstall, skipping default install.
+```
+
+### Parallel Builds
+
+The proxy server uses dynamic ports, so you can run multiple projects in parallel:
+
+```bash
+cd project1 && yarn &
+cd project2 && yarn &
+```
+
+Each project will use a different port (e.g., `49152` and `49153`).
+
+## Temporary Files
+
+The script generates two temporary files during execution:
+
+- **`.registry-proxy-install.lock`**:
+   - Purpose: Prevents the script from running multiple times in the same project (avoids loops caused by `yarn install`).
+   - Location: Always placed in the project root directory (where `package.json` resides).
+- **`.registry-proxy-port`**:
+   - Purpose: Stores the dynamic port number of the proxy server.
+   - Location: Always placed in the project root directory.
+
+### Preventing Misplacement
+
+- The script dynamically determines the project root by locating `package.json`, ensuring temporary files are always placed in the correct location, even if `yarn` is run from a subdirectory (e.g., `cd src && yarn`).
+- If the project root cannot be found, the script will exit with an error:
+  ```
+  Error: Could not find project root (package.json not found)
+  ```
+
+### Cleanup
+
+- Temporary files are automatically removed:
+   - On successful completion of the script.
+   - On interruption (e.g., `Ctrl+C`).
+- The script uses signal handling (`trap`) to ensure cleanup occurs even if interrupted.
+
+## Notes
+
+1. **Strict Mode**:
+   - The script uses Bash strict modes (`set -e`, `set -u`, `set -o pipefail`) to ensure robust error handling:
+      - `set -e`: Exits on any command failure.
+      - `set -u`: Exits on undefined variables.
+      - `set -o pipefail`: Exits if any command in a pipeline fails.
+
+2. **Parallel Execution**:
+   - The lock file (`.registry-proxy-install.lock`) prevents multiple executions within the same project but does not affect different projects.
+   - If you need to run multiple `yarn` processes in the same project (e.g., in a CI environment), consider using a unique lock file per process (e.g., based on process ID).
+
+3. **Dependencies**:
+   - Ensure `nc` (netcat) is installed for port availability checks.
+   - The script uses `npx` to run `registry-proxy`, so no pre-installation is required.
+
+## Troubleshooting
+
+### Proxy Server Fails to Start
+
+- **Symptom**: `Error: Proxy server failed to start`
+- **Possible Causes**:
+   - The specified `REGISTRY_PROXY_VERSION` is invalid.
+   - Network issues prevent `npx` from downloading the package.
+- **Solution**:
+   - Verify the version: `REGISTRY_PROXY_VERSION=latest yarn`.
+   - Check network connectivity and retry.
+
+### Temporary Files Not Cleaned Up
+
+- **Symptom**: `.registry-proxy-install.lock` or `.registry-proxy-port` remains after script execution.
+- **Possible Cause**: The script was terminated abnormally (e.g., `kill -9` instead of `Ctrl+C`).
+- **Solution**:
+   - Manually remove the files:
+     ```bash
+     rm -f .registry-proxy-install.lock .registry-proxy-port
+     ```
+   - Use `Ctrl+C` or `kill -TERM` to ensure proper cleanup.
+
+### Yarn Install Fails
+
+- **Symptom**: `yarn install` fails with a network error.
+- **Possible Cause**: The proxy server did not start correctly, or the registry is unreachable.
+- **Solution**:
+   - Check the proxy server logs (output by `registry-proxy`).
+   - Verify the registry URLs in `.registry-proxy.yml`.
+
+## Testing
+
+### Normal Installation
+
+```bash
+cd project1
+yarn
+```
+
+### Subdirectory Installation
+
+Run `yarn` from a subdirectory to verify that temporary files are placed in the project root:
+
+```bash
+cd project1/src
+yarn
+ls ../.registry-proxy-install.lock ../.registry-proxy-port
+```
+
+### Interrupt Handling
+
+Run `yarn` and press `Ctrl+C` during execution to verify cleanup:
+
+```bash
+cd project1
+yarn
+# Press Ctrl+C after "Waiting for proxy server to start..."
+ls .registry-proxy-install.lock .registry-proxy-port
+```
+
+Expected output: Files should not exist.
+
+### Parallel Builds
+
+Run multiple projects in parallel to verify port allocation:
+
+```bash
+cd project1 && yarn &
+cd project2 && yarn &
+```
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feature-name`.
+3. Commit your changes: `git commit -m "Add feature"`.
+4. Push to the branch: `git push origin feature-name`.
+5. Open a pull request.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

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,51 @@ 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;
+            }
+            const addressInfo = address;
+            const actualPort = addressInfo.port;
+            // 从环境变量获取项目根目录，写入端口文件
+            const projectRoot = process.env.PROJECT_ROOT || process.cwd();
+            const portFilePath = join(projectRoot, '.registry-proxy-port');
+            console.log(`Proxy server started at http://localhost:${actualPort}`);
+            writeFileSync(portFilePath, 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.6",
   "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'; // 导入 AddressInfo 类型
 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,57 @@ 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;
+            }
+
+            const addressInfo: AddressInfo = address;
+            const actualPort: number = addressInfo.port;
 
-    return server;
+            // 从环境变量获取项目根目录，写入端口文件
+            const projectRoot = process.env.PROJECT_ROOT || process.cwd();
+            const portFilePath = join(projectRoot, '.registry-proxy-port');
+            console.log(`Proxy server started at http://localhost:${actualPort}`);
+            writeFileSync(portFilePath, 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);