跳转至

基础设施-部署-dist未重建导致新栏目缺失

问题现象

在 main 分支新增"获取记录"栏目（含前端组件 FetchRecords.vue、路由注册、后端 API）并推送后，服务器 news.queding.hk 页面不显示该栏目，侧边栏只有旧菜单项（共 9 项，缺少第 10 项"获取记录"）。

核心问题

  • 前端 dist 未重新构建：提交 3613e2c 包含了 FetchRecords.vue、fetch-records.ts、路由注册等源码，但 web/dist/ 产物未更新。git log web/dist/ 显示最后一次 dist 更新仍是之前的提交 3855924。
  • 服务器无法自行构建：服务器内存仅 ~570MB，pnpm build 会在 Rollup 打包阶段 OOM 崩溃，因此 .gitignore 移除了 web/dist/，产物随源码一起推送。
  • nginx 直接读取 dist 文件：架构上 nginx 以 root /www/news/web/dist 直接服务静态文件，没有 build 步骤，故 dist 缺什么就显示什么。后端代码和 API 均正常（curl localhost:8000/api/fetch-records 返回 auth 响应），问题纯粹在前端静态产物层面。

解决方法

  1. 本地重新构建 dist（Windows）： 

    cd web && pnpm build
    完成后再确认产物包含 FetchRecords 相关文件： 
    ls web/dist/assets/FetchRecords-*

  2. 提交 dist 并推送到 Git： 

    git add -f web/dist/
git commit -m "chore: rebuild dist with FetchRecords component"
git -c http.proxy= -c https.proxy= push origin main

    注意：如果本地 HTTP 代理（127.0.0.1:7897）不通，GitHub 连接会超时，需用 -c http.proxy= 绕过。

  3. 服务器拉取代码（无需重启任何服务）： 

    # 通过 paramiko SSH（Windows Git Bash 无 sshpass）
cd /www/news && git pull origin main
    由于 nginx 直接从 web/dist/ 读取文件，git pull 后文件立即生效，不需要 systemctl restart。

  4. 验证： 

    # 确认 FetchRecords 文件存在
ls /www/news/web/dist/assets/FetchRecords-*
# 确认 nginx 可访问
curl -s -o /dev/null -w "%{http_code}" -k https://news.queding.hk/assets/FetchRecords-PJh93uQo.js
# 应返回 200

下次防错措施

  1. 前端变更后必须重新构建 dist：任何涉及 web/src/ 源码修改的提交，推送前必须执行 pnpm build 并提交产物。可在 .codebuddy/skills/git/SKILL.md 中添加部署 checklist。

  2. 部署后验证前端完整性：每次部署后，通过脚本对比本地和服务器的 web/dist/assets/ 文件列表，确保关键 chunk 已落地： 

    # 本地
ls web/dist/assets/ | sort > /tmp/dist_local.txt
# 服务器
ssh root@120.77.218.217 "ls /www/news/web/dist/assets/" | sort > /tmp/dist_remote.txt
diff /tmp/dist_local.txt /tmp/dist_remote.txt

  3. 提交前自检清单：在提交代码前回答三个问题：

  4. 本次修改是否涉及前端源码？→ 是，则必须 pnpm build 并提交 dist
  5. 本次修改是否涉及后端路由/Python 源码？→ 是，部署后需 systemctl restart news-backend
  6. 本次修改是否只是静态文件更新？→ 无需重启任何服务