## [ERR-20260415-002] next.config.ts 里的环境变量不会被 .env.local 热加载

**日期**: 2026-04-15
**类别**: Next.js / Dev Server
**严重度**: 低（只要知道"改了 env 必须重启"就能避开）

### 问题描述
为了公网访问，在 `frontend/.env.local` 新增 `BACKEND_PORT=3501` 供 [next.config.ts](frontend/next.config.ts) 的 `rewrites()` 读取。但前端 dev server 是在我改 `.env.local` **之前**就启动的，页面访问 `/api/v1` 一直返回 500（Next 代理到 `localhost:3101` 失败）。

### 根本原因
- `next.config.ts` 在 **Next 进程启动时一次性求值**，里面读到的 `process.env.BACKEND_PORT` 是进程启动那一刻的值。
- Next.js 虽然会在 `.env.local` 变化时自动重载页面代码，但 **不会重新执行 `next.config.ts`**。所以 rewrites/redirects/headers 里用到的 env 不会更新。
- 同理，通过 `npm run dev` 间接设置的 port（如 `next dev -p ${PORT:-3000}`）也要在启动前就把 `PORT` 准备好，否则得杀进程重启。

### 诊断命令
```
cat /proc/$(pgrep -f 'next-server' | head -1)/environ | tr '\0' '\n' | grep -iE 'BACKEND_PORT|NEXT_PUBLIC'
```
直接看正在跑的 next-server 进程里**实际生效的 env**，避免只看文件产生"改完就生效"的错觉。

### 解决方案
凡是修改了会被 `next.config.*` 读取的环境变量（如 `BACKEND_PORT`、rewrites 里用到的任何 env），必须 **Ctrl+C 杀掉 `npm run dev` 并重新启动**，热重载无效。

### 预防措施
- 写 `next.config.ts` 时如果依赖 env，就在 README / 启动脚本里注明"改此变量需重启 dev server"。
- 公网/反代配置时，优先在 Caddy/nginx 侧处理端口路由（reverse_proxy 到正确端口），不要把端口硬编码进 `next.config.ts` 的 rewrites——减少两端同步成本。
- 单 worktree 场景，Caddy 直接指向前端 dev 正在监听的端口（比如默认 3000）即可，不强求用 worktree 端口范围。

### Metadata
- Reproducible: yes（改 .env.local 中被 next.config 读取的 var，不重启前端必现）
- Related Files: frontend/.env.local, frontend/next.config.ts

---