fix(dev): 本地 API 默认端口改为 3100 避开 Windows 保留段

Hyper-V 常保留 2960-3059，3000 会 EACCES；ensure-port-free 与 Vite 代理从 apps/api/.env 读取 PORT

.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=
 

apps/admin/vite.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
 import { resolve } from 'path';
+import { resolveApiDevTarget } from '../../scripts/dev-api-target.mjs';
 import { visualizer } from 'rollup-plugin-visualizer';
 import AutoImport from 'unplugin-auto-import/vite';
 import Components from 'unplugin-vue-components/vite';
@@ -8,6 +9,7 @@ import { ElementPlusResolver } from 'unplugin-vue-components/resolvers';
 
 export default defineConfig(({ mode }) => {
   const analyze = process.env.ANALYZE === '1' || mode === 'analyze';
+  const apiTarget = resolveApiDevTarget();
 
   return {
   plugins: [
@@ -75,8 +77,8 @@ export default defineConfig(({ mode }) => {
   server: {
     port: 5174,
     proxy: {
-      '/api': { target: 'http://localhost:3000', changeOrigin: true },
-      '/uploads': { target: 'http://localhost:3000', changeOrigin: true },
+      '/api': { target: apiTarget, changeOrigin: true },
+      '/uploads': { target: apiTarget, changeOrigin: true },
     },
   },
 };

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",

apps/player/vite.config.ts

@@ -1,6 +1,9 @@
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
 import { resolve } from 'path';
+import { resolveApiDevTarget } from '../../scripts/dev-api-target.mjs';
+
+const apiTarget = resolveApiDevTarget();
 
 export default defineConfig({
   plugins: [vue()],
@@ -37,8 +40,8 @@ export default defineConfig({
   server: {
     port: 5173,
     proxy: {
-      '/api': { target: 'http://localhost:3000', changeOrigin: true },
-      '/uploads': { target: 'http://localhost:3000', changeOrigin: true },
+      '/api': { target: apiTarget, changeOrigin: true },
+      '/uploads': { target: apiTarget, changeOrigin: true },
     },
   },
 });

scripts/dev-api-target.mjs

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** 本地 dev 默认端口；3000 在部分 Windows（Hyper-V 保留 2960–3059）上会 EACCES */
+const DEFAULT_DEV_API_PORT = '3100';
+
+/** 与 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 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()}`;
+}

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 = '';