csscodesplit设为false可将所有非内联css合并为单个style.css,提升缓存效率、避免fouc、防止样式重复;设为true则按入口/动态导入拆分css,但仅物理拆分,不自动异步加载。

直接在 vite.config.js 的 build 选项里设 cssCodeSplit: true 或 false 即可。它不控制 JS 分割,只决定 CSS 是拆成多个文件,还是合并为一个。
关闭 cssCodeSplit:推荐大多数项目使用
设为 false 后,所有非内联样式(import './xxx.css'、组件内 <style></style>、@import)都会打包进单个 style.css,并注入 HTML 的 中。这样更可控,也更利于缓存。
- 避免 FOUC(页面闪白),因为样式加载时机统一且可预测
- 防止重复打包 reset、变量等公共样式,减小总体积
- 浏览器对单个 CSS 文件缓存更高效,尤其配合 HTTP/2 或 CDN
- SSR 场景下服务端能准确提取全部用到的 CSS,不再漏样式
开启 cssCodeSplit:仅限特定需求场景
保持默认 true 或显式设为 true,Vite 会把不同入口或动态导入模块中的 CSS 拆成独立 chunk(如 index-xxx.css、async-xxx.css)。但注意:这仅是物理拆分,不是自动异步加载。
- 只有当 CSS 来自
import()动态导入的模块(如路由组件)时,才会随 JS chunk 异步加载并注入 - 静态
import './global.css'仍会打进主包,无法拆分 -
build.rollupOptions.output.manualChunks对 CSS 完全无效,不能靠它控制 CSS 分块 - 若需主题切换等动态样式,建议用 JS 手动管理
<link>,而非依赖构建时分割
配置写法与注意事项
只需一行配置,无需额外插件:
export default defineConfig({
build: {
cssCodeSplit: false // 关闭;true 则开启
}
})
- 该设置不影响 JS 的
import()动态导入行为,JS 依然按需分割 - CSS 输出文件名可通过
build.rollupOptions.output.assetFileNames自定义,例如'assets/css/[name].[hash].css' - 若用了第三方 UI 库(如 Element Plus),关闭
cssCodeSplit后,务必改用按需引入单组件样式,避免全量加载
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











