huihuiSquare/overview-style-fix-2026-07-21.md

全站样式消失事故 — 根因与修复（2026-07-21）

现象

用户反馈：线上 http://192.168.1.188:8099「样式都全没了」。

根因（部署脚本 bug，非业务代码）

早前部署使用：

docker cp /root/avatar-test/run-dist/. avatar-test-frontend:/usr/share/nginx/html/

这个 SRC/. 写法不可靠——它把新 JS 拷进容器，却漏拷了新 CSS。 结果是容器内变成「新 JS + 旧 CSS」组合：

• Vue <style scoped> 的样式靠 data-v-xxxxxx 作用域属性匹配；
• 新 JS 渲染元素用 data-v-732791c8，但容器内唯一的 AvatarCreate-CslCRBwi.css 是旧构建、用 data-v-8333551b；
• 二者 scope id 不一致 → 样式被浏览器静默丢弃 → 所有页面全站样式失效。

本地 dist 同源构建是自洽的（JS scope == CSS scope），证明问题只发生在 docker cp 拷贝环节。

修复

改用显式子目录拷贝（可靠）：

docker cp /root/avatar-test/run-dist/assets/.  avatar-test-frontend:/usr/share/nginx/html/assets/
docker cp /root/avatar-test/run-dist/index.html  avatar-test-frontend:/usr/share/nginx/html/index.html

整体覆盖后，各页面 JS/CSS 的 scope id 全部对齐：

• AvatarCreate = data-v-732791c8（JS==CSS ✅）
• AvatarManage = data-v-007cc632（JS==CSS ✅）
• SmsLogin = data-v-7851357e（JS==CSS ✅）

验证（无头浏览器实测）

• Playwright(chromium) 渲染 :8099：控制台 0 报错，页面 DOM 正常渲染。
• computed style 实测：
  • .hero 背景 = linear-gradient(135deg, rgb(249,115,22), rgb(251,146,60), rgb(253,186,116))（暖色渐变生效）
  • .feature-card 背景 = rgb(255,255,255)（白卡生效）

→ 样式确凿恢复。

部署铁律（写入项目记忆）

Vite SPA 部署到 docker nginx 容器，禁止 docker cp run-dist/. html/。 一律拆成 assets/. 与 index.html 两条显式拷贝；或先 rm -rf assets/* 再 cp。 每次部署后核对「线上 JS scope id == 同页 CSS scope id」，否则 scoped 样式会静默失效而难以察觉。

测试地址：http://192.168.1.188:8099（建议硬刷新清掉旧 JS/CSS 缓存）。