Vortigern 样式方案拆解：CSS Modules + PostCSS-Assets 完整配置指南

Vortigern 样式方案拆解：CSS Modules + PostCSS-Assets 完整配置指南

【免费下载链接】vortigernA universal boilerplate for building web applications w/ TypeScript, React, Redux, Server Side Rendering and more.项目地址: https://gitcode.com/gh_mirrors/vo/vortigern

🧭Vortigern是一款基于 TypeScript、React、Redux 的通用型 Web 应用脚手架，原生支持服务端渲染（SSR）。它的样式方案由三个角色组成：CSS Modules负责样式隔离，postcss-cssnext负责现代化语法，PostCSS-Assets负责图片路径与雪碧图处理。本文带你完整拆解这套 CSS 配置，帮助你快速在自己的项目中复刻同款能力。

一、为什么是这三件套？

在 SSR 项目中，这三者组合尤其关键：类名必须确定性地哈希（服务端和客户端生成一致的 class），而 PostCSS-Assets 的relative: true则保证相对路径的图片引用在打包前后都正确解析。相关依赖声明在 package.json 中。

二、CSS Modules 配置：一套规则，双轨处理

打开开发环境配置 config/webpack/dev.js，Vortigern 对.css文件定义了两条规则：

• src/app内的样式→ 启用 CSS Modules
• 其余样式（如第三方库）→ 普通全局 CSS

核心 loader 链如下：

'css-loader?modules&importLoaders=2&localIdentName=[local]___[hash:base64:5]'

关键参数解读

[local]___[hash:base64:5]的命名策略值得学习：既保留了可读性（方便调试时对照源码），又通过哈希避免冲突，且两端渲染结果一致，天然适配 SSR。

三、PostCSS 插件链：Stylelint + cssnext + Assets

在 config/webpack/dev.js 中，通过LoaderOptionsPlugin统一注入了 PostCSS 插件链，执行顺序固定为：

postcss: function () { return [ stylelint({ files: '../../src/app/*.css' }), postcssNext(), postcssAssets({ relative: true }), ]; }

⚙️ 三个插件各司其职：

1. stylelint：构建时静态检查样式书写规范，问题早发现；
2. postcss-cssnext：自动补齐浏览器前缀、支持 autoprefixer、自定义属性等现代 CSS 特性；
3. postcss-assets：重写url()引用，relative: true让路径以 CSS 文件为基准解析，配合url-loader完成图片内联或输出。

📌 注意：生产配置 config/webpack/prod.js 使用完全相同的插件链，保证开发/生产行为零差异。

四、三种运行环境下的 Loader 差异

Vortigern 按环境拆分了三份 webpack 配置，CSS 的处理策略各不相同：

💡 生产构建通过ExtractTextPlugin将 CSS 抽取为css/[name].[hash].css，文件名带哈希可放心做长期缓存；SSR 侧则用isomorphic-style-loader替代style-loader，避免 Node 环境下操作 DOM。

五、在组件中使用样式：三行代码

业务侧的使用方式极其简单，以 src/app/containers/Home/index.tsx 为例：

const style = require('./style.css'); <div className={style.Home}>

对应的样式文件 src/app/containers/Home/style.css 只需写普通 CSS：

.Home { text-align: center; }

编译后.Home会被转换为哈希类名，组件之间零冲突。测试代码同样通过require('./style.css')获取真实类名做断言，无需硬编码。

六、快速上手：克隆并运行 Vortigern

git clone https://gitcode.com/gh_mirrors/vo/vortigern cd vortigern npm install npm start # 开发模式（含热更新） npm run build:prod # 生产构建，CSS 自动提取

七、总结：可以带走的设计清单

🎯 从 Vortigern 的样式方案中，新手可以提炼出四条最佳实践：

1. 按目录区分 CSS Modules 与全局 CSS，一条include/exclude规则即可双轨并行；
2. 类名哈希保留原类名（[local]___[hash:base64:5]），调试体验与冲突隔离兼得；
3. PostCSS 插件链集中在 LoaderOptionsPlugin 配置，开发、生产保持一致；
4. SSR 场景用 isomorphic-style-loader 替换 style-loader，这是很多通用脚手架容易遗漏的一步。

掌握这套 CSS Modules + PostCSS-Assets 组合后，你即可在任何 React 项目中搭建出可维护、无冲突、SSR 友好的样式体系。

【免费下载链接】vortigernA universal boilerplate for building web applications w/ TypeScript, React, Redux, Server Side Rendering and more.项目地址: https://gitcode.com/gh_mirrors/vo/vortigern