构建失败时应先检查PostCSS插件顺序、Tailwind content配置、css-loader modules配置、VS Code css.validate设置；逐一排查并精简插件链是最有效方法。
构建失败时先看 postcss 插件链顺序
PostCSS 插件执行顺序直接影响结果，比如 autoprefixer 必须在 cssnano 之后运行，否则压缩可能删掉尚未加前缀的声明。常见错误是把 postcss-preset-env 放在 cssnano 前面，导致特性降级被压缩器误判为冗余而移除。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 用
console.log在自定义 PostCSS 插件中打印root.toString()，确认每一步输出是否符合预期 - 临时注释掉除
autoprefixer外的所有插件，逐步解禁，定位首个引发异常的插件 - 检查插件版本兼容性——
postcssv8+ 不兼容旧版postcss-cssnext，会静默跳过或报Cannot read property 'postcss' of undefined
tailwindcss 的 content 配置错误导致空 CSS 输出
Tailwind v3+ 默认启用 JIT 模式，若 content 路径未覆盖实际使用的 class 字符串（如写成 ./src/**/*.{js,ts} 却在 .tsx 文件里写 class），构建后 CSS 文件可能为空或仅含重置规则，但不报错。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 运行
npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch --verbose查看扫描到的 class 列表 - 确保
content中的 glob 模式匹配真实文件扩展名，.jsx、.mdx、.astro都要显式列出 - 避免在
content中使用node_modules路径——Tailwind 不扫描依赖包内的 class 引用，且可能触发无限递归
Webpack 中 css-loader 和 style-loader 的 modules 配置冲突
当同时启用 CSS Modules 和全局样式处理时，css-loader 的 modules 选项若配置为布尔值 true，会导致所有 .css 文件都被视为模块，包括第三方库的样式（如 normalize.css），从而产生 Module not found: Can't resolve 'xxx.module.css' 类错误。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 改用
modules: { mode: 'local' }并配合test正则精准匹配模块文件，例如/\.module\.css$/ - 为全局 CSS 单独配一条规则，
exclude: /\.module\.css$/，并禁用modules - 注意
style-loader的injectType若设为'lazyStyleTag'，需确保入口 JS 主动调用useStyles()，否则样式不生效且无提示
VS Code 的 css.validate 开关干扰真实构建行为
编辑器内置的 CSS 校验（"css.validate": true）会在保存时高亮语法问题，但它不参与构建流程；而用户常误以为“没红波浪线=能通过构建”，结果 postcss-import 导入路径错误、或 @layer 嵌套层级越界等语义问题仍会导致构建失败。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 关闭
css.validate，改用stylelint+postcss-reporter在命令行构建时统一反馈 - 在
package.json的build脚本末尾加&& echo "✅ CSS built"，避免静默失败 - 注意某些插件（如
postcss-discard-comments）会删除/* stylelint-disable */注释，导致后续校验误报
工具链越深，错误信号越容易被上层吞掉。最有效的排查动作不是加新工具，而是砍掉一半插件再试一次——尤其是那些你“觉得应该没问题”的默认配置。
