静态构建与部署排错

开发服务器会帮我们处理热更新、错误提示和临时资源路径。生产环境使用构建后的文件、真实域名和独立进程，因此还需要单独完成生产验证。

开发模式验证↓生产构建验证↓服务器访问验证

部署排错的关键，是把构建、服务器、代理和浏览器分成不同层逐个验证。

1. 生产部署需要单独验证

开发模式可能允许更宽松的导入方式，也可能自动读取本地环境变量。生产构建会压缩代码、检查类型并提前生成页面。

npm run buildnpm run start

上线前先在本地运行生产构建，可以更早发现缺少依赖、大小写错误和只能在浏览器运行的代码。

2. 构建阶段到底做了什么

构建会把源代码转换成浏览器和服务器实际执行的产物。

读取源码和配置↓检查类型与依赖↓拆分客户端和服务端代码↓生成静态资源或服务端产物↓输出构建目录

不要手动修改构建目录，因为下一次构建会覆盖它。真正的修复应该回到源码和配置。

3. 环境变量为什么经常失效

有些变量在构建时写入产物，有些在服务启动时读取。两种时机混淆后，就会出现服务器已经设置变量但前端仍然使用旧值的情况。

NEXT_PUBLIC_API_BASE=https://api.example.comDATABASE_URL=mysql://app:password@127.0.0.1/app

暴露给浏览器的变量不能包含秘密。修改构建期变量后通常需要重新构建，单独重启服务不会更新已经写入产物的值。

4. 路径和静态资源怎样排查

图片或脚本出现 404 时，先查看浏览器实际请求了哪个 URL。

期望：/assets/logo.svg实际：/notes/assets/logo.svg

接着检查资源是否进入构建产物、基础路径是否正确，以及 Nginx 的 root、alias 和缓存规则。

5. 日志应该从哪一层开始看

从最靠近用户的一层逐步向内检查：

curl -I https://example.comsudo tail -n 100 /var/log/nginx/error.logjournalctl -u webapp -n 100 --no-pagercurl -I http://127.0.0.1:3000

如果 Nginx 返回 502，重点检查上游服务。如果页面返回 200 但浏览器脚本报错，就应该查看前端控制台和资源请求。

6. 一次部署排错的完整顺序

可以使用下面这条固定链路：

确认生产构建成功↓确认构建产物完整↓确认应用进程正常↓确认本机端口可以访问↓确认 Nginx 能连接上游↓确认域名与 HTTPS 正常↓确认浏览器资源和控制台

每通过一层，就缩小一次问题范围。一次只修改一个变量，并记录修改前后的结果，才能避免把偶然恢复误认为真正修复。