Gatsby 官方 Stylus 插件 gatsby-plugin-stylus:接入指南、配置选项与版本演进全解析

原创2026-09-20 22:48:301,924 阅读
文章标签:前端静态站点Web框架

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):

  1. 在 gatsby-config.js 的 plugins 数组中注册插件;
  2. 编写 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」两种写法:

示例站点的 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 等)。

演进脉络解读

将上述时间线串起来,可以清晰看到该插件的能力与质量是如何逐步沉淀的:

  1. 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);
  2. v2.3 时代(2020):修复依赖版本与文档展示(2.3.12),将 ignore 模式加引号避免 shell 解析问题(2.2.3);
  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 的默认行为;
  4. 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 两种样式的编译行为。

登录后查看全文
gatsby