DEBUG.WIKI
京东云;让 AI 进入真实业务;零售 · 物流 · 客服 · 硬件;查看方案 →
ZgoCloud:多地区部署,按需选节点;日本、美国、香港、德国
Evoxt;最高 6.0GHz CPU;高频云服务器 · 免费每周备份;查看配置 →

Vite 多页面构建漏掉 CSS,检查循环 chunk 的样式缓存

Vite 多页面产物漏样式,可能是循环 chunk 的不完整 CSS 列表被后续入口复用。8.3.4 包含缓存准入修复,需逐页核对样式链接与生产显示。

同一个 Vite 多页面项目,开发时两页样式正常,生产构建却有一页缺了整份 CSS。构建没有报错,CSS 文件也在输出目录;真正缺的是该页面 HTML 中的 link rel="stylesheet"。遇到这种组合,先沿生成 chunk 的导入图检查循环,再看 HTML 的样式收集结果。

已确认的一个环境是 macOS ARM64、Node 24.20.0、Vite 8.3.1:两个入口共用 shared 与 feature,这两个 chunk 又互相导入。处理入口的先后顺序不同,缺样式的页面也会变化。Vite 7.3.6 配合手工分块并关闭 hoistTransitiveImports 也能露出同一缺口,因此不能简单归结为某个打包器完全不支持 CSS。

问题出在收集阶段。遍历碰到正在访问的 chunk 时必须停止递归,避免死循环;此时拿到的 CSS 列表还不完整。受影响代码把它放进所有 HTML 入口共享的缓存,后一个入口直接复用这份列表,便漏掉仍在前一条遍历链中的样式。JS chunk 和 CSS 资产可能都已生成,构建成功也就无法保证每份 HTML 引用了正确的样式。

Vite 8.3.4 包含针对这条路径的修复:只有依赖的 chunk 都已有完整缓存,才缓存本 chunk 的 CSS;环中的 chunk 会在后续入口重新遍历。可先在项目分支固定到这个版本:

npm install -D vite@8.3.4
npm ls vite
npm run build

保留原来的多入口、分块和执行顺序配置,方便比较。若配置里的 strictExecutionOrder 是为了保证模块副作用顺序,不宜仅为消除 CSS 症状把它删掉;减少一个环可能暂时改变结果,却不等于修好了样式收集。

验收要逐页检查。例如入口是 index.html 和 dashboard.html,预期两页都使用 shared.css 与 feature.css,就分别查看这两份生成 HTML 的样式链接以及它们对应的实际资产。不要要求输出文件名永远相同:hash 会随构建变化,应按页面需要的样式内容和 chunk 关联判断。连续构建几次,比较每次两页的链接集合,避免只碰巧验到未丢样式的那一页。

接着通过项目现有的生产预览方式打开两个入口,确认相关选择器确实应用,并检查链接状态码。产物已有正确链接但加载 404,应继续查部署路径与 base;链接存在且 CSS 已加载但规则被覆盖,应查层叠顺序。这些情况都不属于这里的缓存缺口。

修复针对的是多 HTML 入口、chunk 循环和不完整 CSS 收集列表复用的组合。它不保证应用源码中的任意循环都安全,也不负责为没有静态关联的样式补链接。诊断时保留缺样式页的生成 HTML、涉及的 chunk 导入关系,以及另一页的对应输出,才能区分“文件没生成”和“文件生成了却没被该页引用”。