[优化] 环境分离

atsf_server/web/next.config.mjs

@@ -1,13 +1,32 @@
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  output: 'export',
-  pageExtensions: ['ts', 'tsx'],
-  images: {
-    unoptimized: true,
-  },
-  eslint: {
-    dirs: ['app', 'components', 'features', 'hooks', 'lib', 'store', 'tests', 'types'],
-  },
-};
-
-export default nextConfig;
+const devBackendUrl =
+  process.env.NEXT_DEV_BACKEND_URL?.replace(/\/+$/, '') || 'http://127.0.0.1:3000';
+const enableDevProxy = process.env.NEXT_DEV_PROXY === 'true';
+
+export default function createNextConfig() {
+  const nextConfig = {
+    output: 'export',
+    pageExtensions: ['ts', 'tsx'],
+    images: {
+      unoptimized: true,
+    },
+    eslint: {
+      dirs: ['app', 'components', 'features', 'hooks', 'lib', 'store', 'tests', 'types'],
+    },
+  };
+
+  if (!enableDevProxy) {
+    return nextConfig;
+  }
+
+  return {
+    ...nextConfig,
+    async rewrites() {
+      return [
+        {
+          source: '/api/:path*',
+          destination: `${devBackendUrl}/api/:path*`,
+        },
+      ];
+    },
+  };
+}

atsf_server/web/package.json

@@ -7,7 +7,8 @@
     "dev": "next dev",
     "build": "next build",
     "postbuild": "node scripts/prepare-static-export.mjs",
-    "start": "next start",
+    "start": "NEXT_DEV_PROXY=true next dev -p 3001",
+    "start:prod": "next start",
     "lint": "eslint . --max-warnings=0",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

docs/app-config.md

@@ -168,19 +168,22 @@ volumes:
 * `OpenRestyCacheEnabled=false` 时，缓存目录与缓存参数应允许留空或回退到默认值
 * 任何包含路径的配置项都必须在 Agent 落盘前再次校验可写性与安全边界
 
-### 1.3 前端构建环境变量
-
-新版管理端位于 `atsf_server/web`，构建时支持以下公开环境变量：
+### 1.3 前端构建环境变量
+
+新版管理端位于 `atsf_server/web`，构建时支持以下公开环境变量：
 
 | 环境变量 | 作用 | 默认值 | 示例 |
 | --- | --- | --- | --- |
-| `NEXT_PUBLIC_API_BASE_URL` | 前端请求后端 API 的基础路径；默认走同源 `/api` | `/api` | `NEXT_PUBLIC_API_BASE_URL=https://demo.example.com/api` |
-| `NEXT_PUBLIC_APP_VERSION` | 构建时注入前端展示版本号 | `dev` | `NEXT_PUBLIC_APP_VERSION=v0.4.0` |
-
-说明：
-
-* 以上变量在前端构建阶段读取，并会被打包进静态资源
-* 推荐生产环境继续使用同源部署，优先保持 `NEXT_PUBLIC_API_BASE_URL=/api`
+| `NEXT_PUBLIC_API_BASE_URL` | 前端请求后端 API 的基础路径；默认走同源 `/api` | `/api` | `NEXT_PUBLIC_API_BASE_URL=https://demo.example.com/api` |
+| `NEXT_PUBLIC_APP_VERSION` | 构建时注入前端展示版本号 | `dev` | `NEXT_PUBLIC_APP_VERSION=v0.4.0` |
+| `NEXT_DEV_BACKEND_URL` | 前端开发服务器通过反向代理转发 `/api/*` 时使用的后端地址；仅开发模式使用 | `http://127.0.0.1:3000` | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3300` |
+
+说明：
+
+* `NEXT_PUBLIC_*` 变量会在前端构建阶段读取，并打包进静态资源
+* `NEXT_DEV_BACKEND_URL` 仅在本地开发服务器模式下使用，不会进入静态导出产物
+* 推荐生产环境继续使用同源部署，优先保持 `NEXT_PUBLIC_API_BASE_URL=/api`
+* `pnpm start` 会以开发模式启动前端，默认监听 `3001`，并通过 `NEXT_DEV_BACKEND_URL` 将 `/api/*` 代理到后端
 
 ---
 

docs/deployment.md

@@ -24,22 +24,40 @@
 
 ## 2. Server 启动
 
-### 2.1 构建前端
-
-```bash
-cd atsf_server/web
-corepack enable
+### 2.1 构建前端
+
+```bash
+cd atsf_server/web
+corepack enable
 pnpm install
 pnpm build
 ```
 
 说明：
 
-* 前端使用 Next.js 静态导出模式构建
-* `pnpm build` 会生成供 Go Server 托管的 `atsf_server/web/build` 目录
-* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL`
-
-### 2.2 启动服务
+* 前端使用 Next.js 静态导出模式构建
+* `pnpm build` 会生成供 Go Server 托管的 `atsf_server/web/build` 目录
+* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL`
+
+### 2.1.1 本地前端热更新开发
+
+在本地联调时，可单独启动前端开发服务器：
+
+```bash
+cd atsf_server/web
+corepack enable
+pnpm install
+pnpm start
+```
+
+说明：
+
+* `pnpm start` 默认以 Next.js 开发模式启动，监听 `http://127.0.0.1:3001`
+* 开发服务器会把 `/api/*` 请求反向代理到 `http://127.0.0.1:3000`
+* 如需改后端地址，可在启动前设置 `NEXT_DEV_BACKEND_URL`
+* 这种模式用于本地热更新开发；正式运行和交付仍以 `pnpm build` 后由 Go Server 托管为准
+
+### 2.2 启动服务
 
 ```bash
 cd atsf_server

docs/frontend-development-guidelines.md

@@ -26,6 +26,13 @@
 * Vitest + Testing Library + Playwright
 * pnpm
 
+本地开发模式：
+
+* `pnpm start`：启动独立前端开发服务器，默认监听 `3001`，支持热更新
+* 开发服务器默认把 `/api/*` 反向代理到 `http://127.0.0.1:3000`
+* 如需改后端地址，可设置 `NEXT_DEV_BACKEND_URL`
+* `pnpm build`：继续用于静态导出，产物交给 Go Server 托管
+
 要求：
 
 * 默认使用 TypeScript，不新增 JS 页面模块