构建后CSS路径不匹配致样式丢失，主因是HTML中link路径与实际部署路径不一致；需正确配置publicPath/base、资源引用方式、提取插件fallback、缓存策略及source map。
构建后 CSS 文件路径不匹配导致样式丢失
开发时用 localhost:3000 直接跑，CSS 通过 /src/index.css 或 import './index.css' 加载没问题；但构建后（如 npm run build）生成的 index.html 里引用的是 ./static/css/main.abc123.css，而服务器实际把资源部署在 /assets/css/ 下，浏览器就 404 了。
关键看构建工具输出的 index.html 中 的路径是否与 Nginx / CDN / 静态托管服务的文件物理路径一致。常见错误包括：
-
public/下手动放的 CSS 被忽略，构建时没走打包流程，hash 不一致或路径硬编码失效 -
webpack.config.js中output.publicPath设为'/'，但项目实际部署在子路径（如https://example.com/my-app/），应设为'/my-app/' - Vite 项目未配置
base，默认base: '/'，需改vite.config.ts：base: '/my-app/'
CSS 中的相对路径资源（如 background-image）在构建后断链
CSS 里写 background: url('./icon.png') 看似简单，但 Webpack/Vite 在构建时会解析并重写这个 URL —— 前提是它能被识别为模块依赖。如果图片放在 public/ 目录下，且用的是绝对路径（如 url('/icon.png')），那构建过程不会处理它，也不会复制、重命名或加 hash，上线后容易因缓存或路径变更失效。
正确做法取决于资源归属：
立即学习“前端免费学习笔记（深入）”；
- 属于组件局部资源 → 放
src/assets/，用url('./icon.png')，由打包器自动处理 - 需全局可访问且不参与构建（如 favicon）→ 放
public/，但在 CSS 中必须用绝对路径url('/icon.png')，并确保部署时该路径真实存在 - 用了 CSS-in-JS 或动态插入 style 标签 → 路径拼接容易出错，建议统一用
new URL('./xxx', import.meta.url)（Vite）或require('./xxx')（Webpack）来获取运行时路径
生产环境启用 CSS 提取（MiniCssExtractPlugin）但未适配热更新或 source map
开发时用 style-loader 把 CSS 插入 标签，修改实时生效；生产用 MiniCssExtractPlugin 输出独立 CSS 文件。如果插件配置漏掉 fallback 或条件判断错误，可能导致开发环境也尝试提取，结果样式全丢。
典型错误配置：
new MiniCssExtractPlugin({
filename: 'css/[name].[contenthash:8].css'
})这会在 dev 和 prod 都启用，但 dev 没配 fallback: 'style-loader'，导致 HMR 失效。应按模式区分：
- Webpack：用
mode === 'production' ? MiniCssExtractPlugin.loader : 'style-loader'作为 rules.use[0] - Vite：默认已处理，无需手动配 loader，但若用了
build.cssCodeSplit: false，所有 CSS 合并进 JS，可能触发 CSP 或加载阻塞 - source map 未开启：生产 CSS 报错定位不到源文件，可在
css-loader中加sourceMap: true，并确保devtool: 'source-map'（Webpack）或build.sourcemap: true（Vite）
CDN 或代理层缓存了旧版 CSS 文件
明明重新构建上传了新 CSS，浏览器仍加载旧样式。不是代码问题，是缓存链路太长：本地 Service Worker → 浏览器内存缓存 → CDN 边缘节点 → 反向代理（如 Nginx 的 proxy_cache）→ 源站。
验证方式很简单：直接请求 CSS 文件 URL，看响应头中 Cache-Control 和 ETag 是否变化；或者加时间戳参数临时绕过：main.css?t=1712345678（仅调试用）。
根治方法靠资源指纹和缓存策略配合：
- 确保构建产物文件名含 contenthash（如
main.a1b2c3d4.css），这样 URL 变更强制刷新 - Nginx 配置示例：
location ~* \.css$ { add_header Cache-Control "public, max-age=31536000, immutable"; } - CDN 控制台检查是否启用了「忽略查询参数」或「强制缓存静态资源」，如有，需关闭或设置白名单
最常被忽略的是反向代理层对 304 响应的过度复用 —— 它可能缓存了旧的 Last-Modified，导致即使文件已更新，仍返回 304。这时候得清代理缓存，或改用 ETag + no-cache 组合。
