Gatsby 官方 Stylus 插件 gatsby-plugin-stylus:接入指南、配置选项与版本演进全解析
Gatsby 官方 Stylus 插件 gatsby-plugin-stylus:接入指南、配置选项与版本演进全解析
本篇技术指南围绕 Gatsby 官方插件 gatsby-plugin-stylus 展开:它让 Gatsby 站点零配置支持 Stylus 梳理出从 v2.0 beta 到 v5.16 的完整演进脉络。
插件是什么:drop-in 的 Stylus 支持
gatsby-plugin-stylus 是 Gatsby 官方维护的一个样式类插件,其 README 第一句话即点明了定位:Provides drop-in support for Stylus。也就是说,安装并启用该插件后,无需任何额外配置即可在组件中 import/require .styl 样式文件,webpack 会负责将其编译为 CSS 并注入构建产物。在 Gatsby 官方文档的内置 CSS 支持清单中,Stylus 对应的正是这个插件(见 docs/docs/how-to/styling/built-in-css.md)。
该插件由 Ian Sinnott 创建并维护,许可证为 MIT,位于 monorepo 的 packages/gatsby-plugin-stylus 目录下。从 package.json 可以看到它的运行时依赖与约束:
| 项目 | 内容(以仓库当前版本为准) |
|---|---|
| 当前版本 | 5.17.0-next.0 |
| 运行时依赖 | @babel/runtime(^7.20.13)、stylus(^0.54.8)、stylus-loader(^3.0.2) |
| peerDependencies | gatsby:^5.0.0-next |
| Node.js 版本约束 | >=18.0.0 <26(engines 字段) |
| 入口文件 | ./gatsby-node.js(由 src/gatsby-node.js 经 babel 编译产出) |
| 构建脚本 | build: babel 编译 src 到包根目录(忽略 __tests__) |
值得注意 engines 字段中 >=18.0.0 <26 这个显式 Node.js 版本区间,它正是 CHANGELOG 中 v5.16.0 的唯一 Bug Fix("use more explicit node.js version range")所引入的,后面版本演进一节会再展开。
安装与基础接入
安装只需一条命令:
npm install gatsby-plugin-stylus
接入分两步(见 README):
- 在
gatsby-config.js的plugins数组中注册插件; - 编写 Stylus 样式(
.styl文件),并在组件中import/require。
最简单的配置如下:
// gatsby-config.js
module.exports = {
plugins: [`gatsby-plugin-stylus`],
}
之后就可以这样使用:
// src/pages/index.js
import "./index.styl"
仓库中的 examples/using-stylus 是一个完整的可运行示例站点,它的 gatsby-config.js 正是以 gatsby-plugin-stylus 为核心接入的,同时搭配了 gatsby-plugin-offline、gatsby-plugin-google-analytics、gatsby-plugin-typography 等插件,演示了「普通 Stylus」与「CSS Modules」两种写法:
- src/pages/index.js + src/pages/index.styl:普通 Stylus;
- src/pages/css-modules.js + src/pages/css-modules.module.styl:CSS Modules。
示例站点的 README 明确指出:该示例用于演示 gatsby-plugin-stylus 如何配置 webpack 去运行 Stylus 代码,并同时包含普通 Stylus 与 CSS Modules 两种用法。
插件配置选项总览(含源码级解析)
如果需要覆盖默认行为,可以把插件写成对象形式并传入 options。插件核心逻辑在 src/gatsby-node.js,其 onCreateWebpackConfig 钩子会解构出三类配置:
exports.onCreateWebpackConfig = (
{ actions, stage, loaders },
{ cssLoaderOptions = {}, postCssPlugins, ...stylusOptions }
) => { ... }
也就是说,插件的配置空间由三部分组成:
| 配置项 | 作用 | 默认值 |
|---|---|---|
stylusOptions(散列参数,含 use、import 等) |
直接透传给 stylus-loader 的选项 |
{} |
cssLoaderOptions |
覆盖传给 css-loader 的选项,例如 camelCase、modules、esModule |
{}(Gatsby 内部使用 css-loader@^5.0.0) |
postCssPlugins |
追加额外的 PostCSS 插件,用于 Stylus 输出的后处理 | 无 |
覆盖 css-loader 选项
README 给出的例子是关闭 CSS Modules 的驼峰转换:
// gatsby-config.js
plugins: [
{
resolve: `gatsby-plugin-stylus`,
options: {
cssLoaderOptions: {
camelCase: false,
},
},
},
]
从源码看,cssLoaderOptions 会被展开进两个规则:普通 .styl 规则中 loaders.css({ importLoaders: 2, ...cssLoaderOptions, modules: false }),CSS Modules 规则中 loaders.css({ ...cssLoaderOptions, importLoaders: 1, modules: cssLoaderOptions.modules ?? true })。
这里有几个源码层细节值得注意:
- 普通
.styl文件强制modules: false:即使你在cssLoaderOptions里写了modules: true,普通规则仍会以modules: false覆盖,因为模块化行为只由文件名后缀.module.styl决定; .module.styl规则中modules默认开启(?? true),可通过cssLoaderOptions.modules自定义;importLoaders不同:普通规则为2(需要经过 postcss 与 stylus 两层前置 loader),模块规则为1(stylus 一层,因为 postcss 在 css-loader 之后执行)——这对应了 css-loader 的 loader 链计数语义;- namedExport:
miniCssExtract的namedExport默认取cssLoaderOptions.modules?.namedExport ?? true,即 CSS Modules 默认按命名导出处理,配合 ES Module 导入实现 tree-shaking(后文展开)。
Stylus 插件与 import 文件
stylusOptions 是剩余参数对象,最常用的两个键是 use(加载 Stylus 插件)和 import(预导入文件),它们与 stylus-loader 的 API 保持一致。源码中 stylusLoader 的构造为:
const stylusLoader = {
loader: resolve(`stylus-loader`),
options: {
...stylusOptions,
},
}
resolve 实现位于 src/resolve.js,只是一个 require.resolve 的薄封装,注释说明「拆出来是为了方便 jest 模拟」,测试里正是通过 mock 它把 loader 路径替换成 /resolved/path/${module}(见 src/tests/gatsby-node.js)。
使用 Stylus 插件:use 选项
README 明确说明:本插件的 API 与 stylus-loader 相同,可以用 use 传入 Stylus 插件,例如响应式布局库 rupture:
// gatsby-config.js
const rupture = require("rupture")
module.exports = {
plugins: [
{
resolve: `gatsby-plugin-stylus`,
options: {
use: [rupture()],
},
},
],
}
examples/using-stylus/gatsby-config.js 底部注释也给出了同样的用法示范。同时 stylusOptions 还支持 import 数组,用于预导入公共变量或 mixin 文件(例如 import: [variables.styl]),测试用例中便覆盖了 import: [file.js, file2.js] 的组合场景。
PostCSS 后处理:postCssPlugins
README 指出:PostCSS 已内置在插件中,用于处理默认优化,例如 autoprefixing(自动加厂商前缀)与常见的跨浏览器 flexbox 兼容问题。正常情况下无需关心,但如果你希望对 Stylus 输出做额外后处理,可以传入 postCssPlugins:
plugins: [
{
resolve: `gatsby-plugin-stylus`,
options: {
postCssPlugins: [somePostCssPlugin()],
},
},
]
在源码中,该配置出现在两条规则的 loaders.postcss({ plugins: postCssPlugins }) 调用处,位于 css-loader 与 stylus-loader 之间。
CSS Modules:零配置开箱即用
CSS Modules 无需任何额外配置,只需把扩展名写成 .module.styl,例如将 app.styl 改名为 app.module.styl 即可。任何带 module 后缀的文件都会走模块化规则(README)。
模块文件以 ES Modules 方式导入以支持 tree-shaking,因此推荐命名导入语法:
import { yourClassName, anotherClassName } from './app.module.styl'
源码层面对应的关键行为:
const stylusRuleModules = {
test: /\.module\.styl$/,
use: [
!isSSR && loaders.miniCssExtract({ modules: { namedExport: cssLoaderOptions.modules?.namedExport ?? true } }),
loaders.css({ ...cssLoaderOptions, importLoaders: 1, modules: cssLoaderOptions.modules ?? true }),
loaders.postcss({ plugins: postCssPlugins }),
stylusLoader,
].filter(Boolean),
}
- 两条规则的匹配分别是
/\.module\.styl$/(优先)与/\.styl$/,并通过oneOf: [stylusRuleModules, stylusRule]组织,保证模块文件命中模块规则; namedExport默认true,这正是「命名导入 + tree-shaking」成立的前提;测试中有一个用例专门验证cssLoaderOptions: { esModule: false, modules: { namedExport: false } }这种「commonjs」风格配置(见 测试文件)。
版本史上与 CSS Modules 相关的两个关键修复值得一提:
- v2.0.5:Disable HMR for CSS modules(issue #11032)——早期 CSS Modules 的热更新存在问题,故被显式禁用;
- v3.2.0:enable better cssOptions override for modules(issue #30112)——即前文所述
cssLoaderOptions.modules?.namedExport ?? true这套「允许更精细覆盖模块相关 css 选项」的机制正是本次 Feature 引入的。
SSR 阶段处理:HTML 构建中不加载样式
源码中有一段专门针对服务端渲染(SSR)的处理:
const isSSR = [`develop-html`, `build-html`].includes(stage)
...
const stylusRule = {
test: /\.styl$/,
use: isSSR
? [loaders.null()]
: [ loaders.miniCssExtract(), loaders.css({...}), loaders.postcss({...}), stylusLoader ],
}
即:在 develop-html 与 build-html 两个 HTML 构建阶段,.styl 普通规则使用 null loader(空 loader),不实际提取 CSS;而 .module.styl 规则则通过 !isSSR && loaders.miniCssExtract(...) 加 .filter(Boolean) 的方式在 SSR 阶段移除 mini-css-extract 环节。这背后是 Gatsby 的整体设计:HTML 静态页面不需要注入样式产物,样式只在浏览器端 JavaScript bundle 中按需加载。
这一行为对应版本史上的两个修复:
- v3.1.0 / v3.0.0:don't use loader in ssr(issue #29801)——明确 SSR 阶段不再使用(样式)loader;
- v3.0.0:make minicss-extract-plugin compatible with plugins(issue #29599)。
而 v4.5.0 的修复 "Update mini-css-extract-plugin to fix inc builds issue"(issue #33979/#33982)与随后的 Revert(issue #34413),则反映了 mini-css-extract-plugin 升级与增量构建(incremental builds)之间的一段兼容性波折,最终在后续版本中稳定下来。
测试与验证
插件自带完整的单元测试,位于 src/tests/gatsby-node.js,覆盖矩阵为「4 个构建阶段 × 5 组选项」:
| 构建阶段 | 选项场景 |
|---|---|
develop |
无选项 |
build-javascript |
use: [stylusPlugin()] |
develop-html |
use + import 组合 |
build-html |
postCssPlugins: [test1] |
cssLoaderOptions:esModule: false + modules.namedExport: false |
测试通过 mock resolve 与 loaders,对 setWebpackConfig 的调用结果做快照断言,快照存放在 src/tests/snapshots/gatsby-node.js.snap。此外,e2e 测试站点(如 e2e-tests/development-runtime/gatsby-config.js 与 e2e-tests/production-runtime)也引入了该插件,作为真实构建链路中的回归验证。
从 CHANGELOG 看版本演进:v2.0-beta 到 v5.16
CHANGELOG.md 遵循 Conventional Commits 规范生成,完整记录了该插件 2018 年 6 月(v2.0.0-beta.0)至今的每一次发布。绝大多数条目是 "Version bump only for package gatsby-plugin-stylus" —— 这是 Gatsby 使用 Lerna monorepo 集中发布机制的直接体现:即使插件源码没有任何改动,只要 monorepo 中其他包升级触发了整体发布,该包版本号也会同步递增。因此解读这份 CHANGELOG 时,应把注意力集中在标注了 Bug Fixes / Features / Chores 实质内容的版本上。
关键时间线一览(含实质变更的版本)
| 版本 | 日期 | 变更类型 | 实质内容 |
|---|---|---|---|
| 5.16.0 | 2026-01-26 | Bug Fixes | 使用更明确的 Node.js 版本区间(issue #39398) |
| 5.6.0 | 2023-02-07 | Bug Fixes | 更新 babel monorepo(#37568) |
| 5.4.0 | 2023-01-10 | Chores | 更新 babel monorepo(#37386) |
| 5.0.0 | 2022-11-08 | Chores | 更新 peerDependencies(#36965)、应用 v5 补丁(#36796) |
| 4.5.0 | 2022-01-11 | Bug Fixes | 更新 mini-css-extract-plugin 修复增量构建问题(#33979/#33982),后又 Revert(#34413) |
| 4.0.0 | 2021-10-21 | Chores | 应用 v4 补丁(#33170) |
| 3.2.0 | 2021-03-30 | Features | 为 CSS Modules 启用更好的 cssOptions 覆盖能力(#30112) |
| 3.1.0 / 3.0.0 | 2021-03 | Bug Fixes | SSR 阶段不再使用 loader(#29801)、mini-css-extract 与插件兼容(#29599) |
| 2.3.12 | 2020-09-28 | Bug Fixes | 更新次要/补丁依赖(#27133)、修复插件库 README 展示问题(#27040) |
| 2.2.3 | 2020-04-17 | Bug Fixes | 将 ignore 模式用引号包裹(#23176) |
| 2.2.0 | 2020-03-20 | Features | Gatsby 最低 Node 版本提升至 10.13.0(#22400) |
| 2.1.2 | 2019-07-12 | Bug Fixes | 修正各包 CHANGELOG 中的链接(#15630) |
| 2.0.5 | 2019-02-01 | Bug Fixes | 为 CSS Modules 禁用 HMR(#11032) |
| 2.0.0-beta.3 | 2018-06-27 | Bug Fixes | import 走语言 loader 而非 postcss(#6173) |
其余 60 余个版本均为纯粹的 "Version bump only"(babel monorepo 升级、cross-env 依赖升级、changelog 格式整理等过程性变更也属于此列,例如 5.4.0/3.7.1/2.7.0/2.5.0/4.9.0 等)。
演进脉络解读
将上述时间线串起来,可以清晰看到该插件的能力与质量是如何逐步沉淀的:
- v2.0 时代(2018-2019):核心是把
.styl文件的 import 走语言 loader 而非 postcss(beta.3),禁用 CSS Modules 的 HMR(2.0.5),修正 changelog 链接(2.1.2),并随 Gatsby 主包将最低 Node 版本提升到 10.13.0(2.2.0); - v2.3 时代(2020):修复依赖版本与文档展示(2.3.12),将 ignore 模式加引号避免 shell 解析问题(2.2.3);
- v3 时代(2021):迎来重要能力升级——SSR 阶段不再使用 loader(3.0.0/3.1.0),mini-css-extract-plugin 与插件体系兼容(3.0.0),以及 CSS Modules 的 cssOptions 精细覆盖(3.2.0),后者直接奠定了当前源码中
cssLoaderOptions.modules?.namedExport的默认行为; - v4/v5 时代(2021-2026):以工程化维护为主——应用大版本补丁(4.0.0/5.0.0)、更新 babel monorepo(5.4.0/5.6.0)、修复增量构建相关的 mini-css-extract 升级问题(4.5.0),并最终在 5.16.0 明确 Node.js 版本区间(对应如今 package.json 中
>=18.0.0 <26的 engines 字段)。
小结
gatsby-plugin-stylus 是一个「小而精」的 Gatsby 官方插件:对外,只需一行 plugins: <a href="https://link.gitcode.com/i/1aa67725868165c0dea7b00942c8d677" target="_blank">gatsby-plugin-stylus] 即可获得 .styl 编译、CSS Modules、PostCSS 与 Stylus 插件四大能力;对内,其 [gatsby-node.js 通过两条 webpack 规则(/\.styl$/ 与 /\.module\.styl$/)加上 oneOf 编排,实现了普通样式与模块化样式的分流,并在 SSR 阶段用 null loader 与 .filter(Boolean) 优雅地剥离样式产物。其 CHANGELOG 则以 2018-2026 近八年的发布记录,成为观察 Gatsby 插件体系工程化演进的绝佳样本。
如需动手验证,可参考 examples/using-stylus 示例站点:npm install 后运行 npm run develop(对应 gatsby develop)或 npm run build(对应 gatsby build),即可在真实构建环境中观察普通 Stylus 与 CSS Modules 两种样式的编译行为。