Mako 项目中 CSS 文件未生效问题解析

2025-07-04 22:51:25作者：羿妍玫Ivan

问题背景

在使用 Mako 构建工具时，开发者可能会遇到一个常见问题：在项目中引入的 CSS 文件没有按预期生效。这种情况通常发生在开发者尝试独立使用 Mako 构建项目时，特别是在非 CSS Module 模式下引用样式文件。

当开发者在项目中通过 JavaScript 文件引入 CSS 样式时（例如使用 import './index.less'），虽然构建过程没有报错，但最终页面上却没有看到预期的样式效果。检查构建产物会发现 CSS 文件确实被正确生成，但浏览器却没有应用这些样式。

这个问题的根本原因在于 HTML 文件中缺少对生成 CSS 文件的显式引用。Mako 作为一个现代化的构建工具，会将 CSS 文件单独提取出来，而不是像传统方式那样将样式内联到 JavaScript 中。因此，开发者需要在 HTML 文件中手动添加对 CSS 文件的链接引用。

要解决这个问题，只需在 HTML 文件的 <head> 部分添加对生成 CSS 文件的链接引用即可：

<link rel="stylesheet" href="/index.css" />

构建流程解析：
- Mako 在构建过程中会将 LESS 等预处理语言编译为 CSS
- 对于非 CSS Module 的引用，会生成独立的 CSS 文件
- 这些 CSS 文件需要被显式引入到 HTML 中才能生效
与传统方式的区别：
- 传统打包工具可能会将 CSS 内联到 JavaScript 中
- Mako 采用了更现代的分离打包策略，保持 CSS 的独立性
- 这种分离有助于更好的缓存策略和加载性能
最佳实践建议：
- 对于全局样式，建议使用显式 HTML 引入
- 对于组件级样式，可以考虑使用 CSS Module 方式
- 在生产环境中，可以考虑添加文件哈希以利用浏览器缓存