node-api-proxy

一个轻量 Node.js 接口代理服务。前端把接口请求发到这个服务，它会自动转发到真实后端服务器。

使用方式

cd node-api-proxy
npm start

作为 npm 包安装到前端项目中：

npm install --save-dev @jiangdr/node-api-proxy

安装后可通过 npm bin 直接启动：

npx node-api-proxy

node-api-proxy 只启动代理服务，不启动业务项目。业务项目需要同时启动前端和代理时，应在业务项目自己的脚本里编排。

启动时会先读取包内 api.proxy.json，再读取当前业务项目根目录的 api.proxy.json 覆盖代理入口配置。

业务项目示例 api.proxy.json：

{
  "PORT": 9080,
  "TARGET_SERVER": "https://staging-syapi.kuaileyouxuan.com",
  "PROXY_PREFIX": "/admin-api",
  "YAPI_MOCK_SERVER": "http://47.111.182.150:3000",
  "yapiCookie": ""
}

修改业务项目根目录 api.proxy.json 里的 TARGET_SERVER 为真实服务器地址：

{
  "PORT": 3001,
  "TARGET_SERVER": "https://your-real-server.com",
  "PROXY_PREFIX": "/api",
  "YAPI_MOCK_SERVER": ""
}

前端请求示例：

fetch('http://localhost:3001/api/user/list')

默认会转发到：

https://your-real-server.com/api/user/list

配置项

| 配置 | 默认值 | 说明 | | --- | --- | --- | | PORT | 3001 | 代理服务端口 | | TARGET_SERVER | https://example.com | 真实后端服务器地址 | | PROXY_PREFIX | /api | 代理前缀配置，用于 STRIP_PREFIX 和 YApi mock 路径归一化；不限制其他前缀请求转发 | | YAPI_MOCK_SERVER | 空 | 真实后端返回 404 时兜底请求的 YApi 地址，可填站点域名或 mock 项目根地址 | | yapiCookie | 空 | 查询 YApi projectId 时使用的登录态 cookie，过期后可在项目配置中更新 |

业务项目根目录的 api.proxy.json 只读取以上五个字段。下面是代理包内部高级配置，按需通过环境变量临时覆盖：

| 配置 | 默认值 | 说明 | | --- | --- | --- | | STRIP_PREFIX | false | 是否转发时移除 PROXY_PREFIX | | ALLOW_ORIGIN | * | CORS 允许来源 | | ALLOW_HEADERS | Content-Type, Authorization, X-Requested-With, X-Request-Id, tenant-id | 浏览器预检未声明请求头时使用的默认允许头 | | ALLOW_CREDENTIALS | false | 是否允许前端携带 Cookie 等凭证 | | TIMEOUT_MS | 30000 | 上游请求超时时间 | | YAPI_DOC_URL | 空 | YApi 接口文档地址；当 YAPI_MOCK_SERVER 只配置到域名时，用它解析项目 ID | | YAPI_PROJECT_ID | 空 | YApi 项目 ID；当 YAPI_MOCK_SERVER 只配置到域名时，用它拼出 /mock/{projectId} | | YAPI_PROJECT_CACHE_FILE | data/yapi-project-cache.json | 接口路径到 YApi projectId 的本地缓存文件 | | MAX_BODY_BYTES | 10485760 | 为了 404 后重试到 YApi，可缓存的最大请求体字节数 |

如果前端请求 /api/user/list，但真实后端接口是 /user/list，启动代理时显式传入：

STRIP_PREFIX=true npx node-api-proxy

如果前端请求需要携带 Cookie，不要使用 ALLOW_ORIGIN=*，应配置为具体前端地址：

ALLOW_ORIGIN=http://localhost:5173 ALLOW_CREDENTIALS=true npx node-api-proxy

YApi mock 兜底

如果真实服务器返回 404，可以让代理自动请求 YApi mock。把 api.proxy.json 配成 YApi mock 项目根地址：

{
  "YAPI_MOCK_SERVER": "http://yapi.example.com/mock/95"
}

也可以只配置 YApi 域名。首次 mock 某个接口时，代理会调用 /api/project/search?q={接口路径} 查询 projectId，并把结果写入 data/yapi-project-cache.json，下次同一路径直接读取缓存：

{
  "YAPI_MOCK_SERVER": "http://47.111.182.150:3000"
}

当前端请求：

http://localhost:3001/admin-api/trade/return-shipping-method/page?pageNo=1&pageSize=10&name=

真实服务器返回 404 时，代理会继续请求：

http://47.111.182.150:3000/mock/95/trade/return-shipping-method/page?pageNo=1&pageSize=10&name=

mock 成功时，代理会保证返回 JSON 中带有 mock: true。如果 YApi projectId 查询失败、mock 请求异常或 mock 返回 4xx/5xx，代理会返回一个合成 JSON，里面同时包含 mockError 和 realResponse，方便前端看到 mock 失败原因和真实接口原始响应。

导出 YApi 接口缓存

需要把当前账号可见的 YApi 项目、接口详情和 mock 返回缓存到本地时，执行：

npm run fetch:yapi

默认输出到 data/yapi-cache.json。脚本优先读取环境变量 YAPI_COOKIE，未设置时再从 ~/.codex/config.toml 读取同名配置作为 YApi 请求登录态，但不会把 cookie 写入 JSON。

默认导出所有可见项目，不会因为代理配置里的单个 YApi 地址只导出一个项目。如果只想刷新指定项目，可以显式指定：

node scripts/fetch-yapi-cache.js --projects=95,119

如果只需要接口文档和 mock 地址，不需要请求 mock 响应：

node scripts/fetch-yapi-cache.js --projects=95,119 --no-mock

前端接入

开发环境把接口 baseURL 指向代理服务即可：

const apiBaseUrl = 'http://localhost:3001';

生产环境通常不需要这个 Node.js 本地代理，可改用 Nginx、网关或后端同源部署方案。