自定义CSS未生效的主因是构建工具未将其注入HTML：Vite/Webpack需显式配置或使用<link>标签，否则import仅建立模块依赖；检查源码无<link>、Network中404或CSS顺序错乱均会导致失效。
自定义CSS文件根本没进HTML的标签里
构建工具（Vite/Webpack）不会自动把你的 style.css 插入 HTML，除非你显式声明。很多人在 main.js 里写了 import './assets/css/style.css'，但忘了它只是模块依赖，不等于生成 <link> 标签——尤其当用的是 Vite 的 CSS 注入模式或 Webpack 的 MiniCssExtractPlugin，输出路径和引用逻辑全靠配置驱动。
检查方法：打开生产环境页面 →「查看网页源代码」→ 搜索 style.css 或你的文件名。如果没找到 <link rel="stylesheet">，说明它压根没被注入。
- Vue CLI 项目：确保
vue.config.js中未禁用css.extract，且public/index.html里没手动删掉动态插入点 - Vite 项目：确认
vite.config.js中build.rollupOptions.output.entryFileNames没把 CSS 输出成 hash 名后丢失映射 - 直接用
public/下的 CSS？别这么做——public/文件不会被哈希、不会走构建流程，CDN 缓存更新后容易 404
路径解析失败导致404，但控制台没报错
Webpack/Vite 在生产构建时会重写静态资源路径，比如把 ./css/custom.css 编译成 /assets/custom.abc123.css。如果你在 HTML 模板里硬编码了旧路径（例如 <link href="css/custom.css">），浏览器就会发请求到不存在的地址，Network 面板显示 404，但控制台可能只报「Failed to load resource」，不提示具体是哪个文件。
常见翻车点：
立即学习“前端免费学习笔记（深入）”；
- Django/Flask 模板中用了
{% static 'css/custom.css' %}，但对应文件实际放在static/css/custom.min.css，少了个.min - Vite 项目里设置了
base: '/myapp/'，但<link>的href写成了绝对路径/css/custom.css，漏了前缀 - 使用了 CSS in JS 或
<style>标签内联，结果构建时被提取插件忽略，或被 PurgeCSS 当作无用代码删掉了
自定义CSS加载顺序被构建工具悄悄调换
你以为 import 'bootstrap/dist/css/bootstrap.min.css'; 在前、import './css/custom.css'; 在后就稳了？不一定。Webpack 的 SplitChunksPlugin 或 Vite 的 CSS 合并策略，可能把所有 CSS 打包进一个 index.css，再按模块依赖图重排顺序——最终 custom.css 的规则物理上出现在 bootstrap.min.css 规则之前。
验证方式：打开生产环境的 index.css（Network 面板找那个最大的 CSS 文件），搜索 .btn，看 Bootstrap 的规则是否在你自定义规则之前出现。
- 最可靠方案：放弃 JS import CSS，改用 HTML 中显式
<link>，并确保它在 Bootstrap 的<link>之后 - 若必须用 import，Vite 用户可在
vite.config.js中加css.preprocessorOptions.sass.additionalData把变量注入全局，但普通 CSS 仍建议走 link - Webpack 用户可配置
mini-css-extract-plugin的insert选项，强制插入到<head>底部
样式被 PurgeCSS 或其他 tree-shaking 工具误删
Bootstrap 5 默认启用类名白名单机制，而 PurgeCSS 这类工具会扫描 JS/HTML 中出现的类名，把「没用到」的 CSS 规则干掉。你写的 .btn.my-btn 如果只在 JS 动态拼接字符串中出现（比如 el.className = 'btn my-btn'），PurgeCSS 很可能识别不到，直接删掉整条规则。
典型症状：开发环境一切正常，build 后按钮变回浏览器默认样式，但 JS 功能还在。
- 检查
tailwind.config.js或purgecss.config.js中的content字段，是否漏扫了 JS 文件或模板字符串 - 给关键自定义类加白名单：
['my-btn', 'c-img', 'dashboard .btn']，避免正则匹配遗漏 - 不要依赖
/* purgecss start ignore */注释——部分构建流程会跳过注释解析
真正卡住人的地方，往往不是「怎么写」，而是「它到底有没有进浏览器」。先查源码里的 <link>，再查 Network 里的 200 响应，最后看 CSS 文件里规则的物理顺序——这三步比调权重、改 !important 管用十倍。
