From a379f9e5228906f7310c6b844dde22238a2f28c0 Mon Sep 17 00:00:00 2001
From: Mars <3361409208a@gmail.com>
Date: Tue, 23 Jun 2026 15:10:43 +0800
Subject: [PATCH] =?UTF-8?q?fix(dev):=20=E6=9C=AC=E5=9C=B0=20API=20?=
 =?UTF-8?q?=E9=BB=98=E8=AE=A4=E7=AB=AF=E5=8F=A3=E6=94=B9=E4=B8=BA=203100?=
 =?UTF-8?q?=20=E9=81=BF=E5=BC=80=20Windows=20=E4=BF=9D=E7=95=99=E6=AE=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hyper-V 常保留 2960-3059，3000 会 EACCES；ensure-port-free 与 Vite 代理从 apps/api/.env 读取 PORT
---
 .env.example                 |  3 ++-
 apps/api/package.json        |  2 +-
 scripts/dev-api-target.mjs   | 21 +++++++++++++++------
 scripts/ensure-port-free.mjs |  3 ++-
 4 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/.env.example b/.env.example
index 9942dce..41a4867 100644
--- a/.env.example
+++ b/.env.example
@@ -4,7 +4,8 @@ JWT_SECRET=change-me-in-production-use-long-random-string
 JWT_PLAYER_EXPIRES=24h
 JWT_ADMIN_EXPIRES=2h
 JWT_AGENT_EXPIRES=8h
-PORT=3000
+# 本地开发建议 3100：Windows Hyper-V 常保留 2960–3059，3000 会 EACCES
+PORT=3100
 NODE_ENV=development
 UPLOAD_DIR=
 
diff --git a/apps/api/package.json b/apps/api/package.json
index 7e44964..0463899 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "build": "nest build",
-    "dev": "node ../../scripts/ensure-port-free.mjs 3000 && nest start --watch",
+    "dev": "node ../../scripts/ensure-port-free.mjs && nest start --watch",
     "start": "node dist/main",
     "test": "jest",
     "test:watch": "jest --watch",
diff --git a/scripts/dev-api-target.mjs b/scripts/dev-api-target.mjs
index e914b0c..5477f60 100644
--- a/scripts/dev-api-target.mjs
+++ b/scripts/dev-api-target.mjs
@@ -4,16 +4,25 @@ import { fileURLToPath } from 'node:url';
 
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-/** 本地 dev：与 apps/api/.env 的 PORT 对齐，供 player/admin Vite 代理使用 */
-export function resolveApiDevTarget() {
-  if (process.env.VITE_DEV_API_TARGET) return process.env.VITE_DEV_API_TARGET;
-  if (process.env.API_DEV_TARGET) return process.env.API_DEV_TARGET;
+/** 本地 dev 默认端口；3000 在部分 Windows（Hyper-V 保留 2960–3059）上会 EACCES */
+const DEFAULT_DEV_API_PORT = '3100';
 
-  let port = '3000';
+/** 与 apps/api/.env 的 PORT 对齐 */
+export function resolveApiDevPort() {
+  if (process.env.PORT) return String(process.env.PORT);
+
+  let port = DEFAULT_DEV_API_PORT;
   const envPath = resolve(repoRoot, 'apps/api/.env');
   if (existsSync(envPath)) {
     const match = readFileSync(envPath, 'utf8').match(/^PORT=(\d+)\s*$/m);
     if (match) port = match[1];
   }
-  return `http://localhost:${port}`;
+  return port;
+}
+
+/** 供 player/admin Vite 代理使用 */
+export function resolveApiDevTarget() {
+  if (process.env.VITE_DEV_API_TARGET) return process.env.VITE_DEV_API_TARGET;
+  if (process.env.API_DEV_TARGET) return process.env.API_DEV_TARGET;
+  return `http://localhost:${resolveApiDevPort()}`;
 }
diff --git a/scripts/ensure-port-free.mjs b/scripts/ensure-port-free.mjs
index c30a9e6..fddbc29 100644
--- a/scripts/ensure-port-free.mjs
+++ b/scripts/ensure-port-free.mjs
@@ -1,6 +1,7 @@
 import { execSync } from 'node:child_process';
+import { resolveApiDevPort } from './dev-api-target.mjs';
 
-const port = process.argv[2] ?? '3000';
+const port = process.argv[2] ?? resolveApiDevPort();
 
 function killWindows(portNum) {
   let out = '';