Storybook Next.js 框架的 CSS Modules 支持零配置使用 CSS/Sass 模块的完整解析【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文聚焦 Storybook 官方文档中「Next.js styling → CSS/Sass/Scss Modules」一节的核心内容在使用storybook/nextjs框架时.module.css、.module.scss、.module.sass这类 CSS Modules 导入可以直接工作无需额外配置。文章先完整保留官方文档给出的可运行代码示例再深入 Storybook 仓库中 Next.js 框架包的源码css/webpack.ts解释「零配置」背后由哪些 Webpack loader 规则与 Next.js 自身的函数协作实现并引用框架自带示例故事Link.stories.tsx作为可验证的落地证据帮助你在 Next.js Storybook 项目中正确落地组件样式方案。一、核心结论CSS Modules 在 Storybook 中开箱即用这一能力定义在 Next.js 框架文档的「Next.js styling」章节中nextjs.mdx 与 nextjs-vite.mdx原文的表述非常简短但信息量明确CSS modules work as expected.CSS Modules 按预期工作。其配套代码片段即本文的核心文档 nextjs-styling-css-modules.md给出了 JS 与 TS 两个版本完整保留如下// This import will work in Storybook import styles from ./Button.module.css; // Sass/Scss modules are also supported // import styles from ./Button.module.scss // import styles from ./Button.module.sass export function Button() { return ( button typebutton className{styles.error} Destroy /button ); }// This import will work in Storybook import styles from ./Button.module.css; // Sass/Scss modules are also supported // import styles from ./Button.module.scss // import styles from ./Button.module.sass export function Button() { return ( button typebutton className{styles.error} Destroy /button ); }从这个示例可以提取出三个关键事实普通 CSS Modules./Button.module.css默认导入得到一个类名映射对象className{styles.error}的写法与在 Next.js 应用里完全一致Sass/Scss 变体同样支持./Button.module.scss和./Button.module.sass不需要单独配置即可使用无需任何 Storybook 侧配置不需要在main配置里写 webpack override也不需要引入额外 loader。二、为什么是「零配置」源码级的实现证据「开箱即用」并非凭空声明。storybook/nextjs框架包内有一个专门负责样式的 Webpack 配置函数 configureCss它完整复刻了 Next.js 官方的 CSS 处理管线。逐段拆解如下。2.1 接管.css规则modules.auto 自动识别 CSS Modulesrules[i] { test: /\.css$/, use: [ fileURLToPath(import.meta.resolve(style-loader)), { loader: fileURLToPath(import.meta.resolve(css-loader)), options: { importLoaders: 1, ...getImportAndUrlCssLoaderOptions(nextConfig), modules: { auto: true, getLocalIdent: getCssModuleLocalIdent, }, }, }, fileURLToPath(import.meta.resolve(postcss-loader)), ], // We transform the target.css files from next.js into Javascript // for Next.js to support fonts, so it should be ignored by the css-loader. exclude: /next(\\|\/|\\\\).*(\\|\/|\\\\)target\.css$/, };代码引自 code/frameworks/nextjs/src/css/webpack.ts#L25-L45这里有两个直接决定「CSS Modules 可用」的关键点modules: { auto: true }让css-loader按文件名自动判定是否启用 modules 模式即*.module.css自动走 modules 管线导出类名对象普通.css文件按全局样式注入。这就是为什么示例中import styles from ./Button.module.css不需要任何额外声明。getLocalIdent: getCssModuleLocalIdent该函数直接来自next/dist/build/webpack/config/blocks/css/loaders/getCssModuleLocalIdent.js见 css/webpack.ts 第 7 行 的导入。由于 Storybook 复用了 Next.js 官方的类名生成函数CSS Modules 在 Storybook 里生成的局部类名与在你的 Next.js 应用里保持一致不会出现「同一组件两边类名哈希不同」的困惑。同时注意exclude: /next.*target\.css$/Next.js 16 会把target.css这类字体文件转成 JS 处理Storybook 明确将其排除在 css-loader 之外避免字体相关资源被二次处理。2.2 接管.scss/.sass规则Sass Modules 与自定义 sassOptionsrules?.push({ test: /\.(scss|sass)$/, use: [ fileURLToPath(import.meta.resolve(style-loader)), { loader: fileURLToPath(import.meta.resolve(css-loader)), options: { importLoaders: 3, ...getImportAndUrlCssLoaderOptions(nextConfig), modules: { auto: true, getLocalIdent: getCssModuleLocalIdent }, }, }, fileURLToPath(import.meta.resolve(postcss-loader)), fileURLToPath(import.meta.resolve(resolve-url-loader)), { loader: fileURLToPath(import.meta.resolve(sass-loader)), options: { sourceMap: true, sassOptions: nextConfig.sassOptions, additionalData: nextConfig.sassOptions?.prependData || nextConfig.sassOptions?.additionalData, }, }, ], });代码引自 code/frameworks/nextjs/src/css/webpack.ts#L48-L72这解释了文档注释中「Sass/Scss modules are also supported」这句承诺的来源\.scss|\.sass被统一纳入同一条管线modules: { auto: true }同样生效所以Button.module.scss、Button.module.sass与Button.module.css行为一致sassOptions: nextConfig.sassOptions你在next.config.js中自定义的 Sass 选项如additionalData全局注入、自定义prependData会被原样传递给sass-loaderStorybook 里的编译结果与 Next.js 项目保持一致resolve-url-loader插在postcss-loader与sass-loader之间解决 Sassimport中相对路径在编译后指向错误的问题注意importLoaders从 CSS 管线的1提升到 Sass 管线的3因为 Sass 规则链上多出了postcss-loader和resolve-url-loader两层需要预处理的 loader。2.3 CSS 内部的 url()/import 解析复用 Next.js 自己的解析器const getUrlResolver (nextConfig: NextConfig) (url: string, resourcePath: string) cssFileResolve(url, resourcePath, nextConfig.experimental?.urlImports);cssFileResolve同样来自next/dist/build/webpack/config/blocks/css/loaders/file-resolve.jscss/webpack.ts 第 6 行。这意味着 CSS Modules 文件里写的url(./icon.png)或import在 Storybook 中的解析规则与 Next.js 完全一致包括experimental.urlImports的行为。从源码结构看这里还有一段兼容性处理 getImportAndUrlCssLoaderOptions它会探测当前实际安装的css-loader版本v6 使用{ url: { filter }, import: { filter } }的新选项结构v5 使用旧的url/import直接传 resolver 的写法探测失败时例如 Storybook 的 Webpack 5 manager 解析到自带 v5 版本默认按 v5 处理。这段逻辑保证了不同依赖树下的 loader 行为都正确属于「无感知」的底层保障。2.4 你的 next.config 是如何被读取的「自动继承 sassOptions / PostCSS 配置」的前提是 Storybook 会先解析你的 Next.js 配置文件。入口在 configureConfigconst nextConfig await resolveNextConfig({ nextConfigPath }); // ... await setupRuntimeConfig(baseConfig, nextConfig);resolveNextConfig会定位并加载项目中的next.config.js/ts/mjs随后configureCss拿到的nextConfig就是这份真实配置对象——sassOptions、experimental.urlImports、publicRuntimeConfig等都从这里取值。此外setupRuntimeConfig还通过DefinePlugin注入了__NEXT_TRAILING_SLASH、__NEXT_NEW_LINK_BEHAVIOR等环境变量保证next/link的 mock 行为与应用端一致config/webpack.ts#L62-L89。三、仓库内的真实使用示例文档里的Button示例是示意性的而框架包自己的示例故事里就有 CSS Modules 的真实用法可直接作为参照样式文件 Link.stories.module.css.link { color: green; }使用处 Link.stories.tsximport style from ./Link.stories.module.css; // ... Link className{style.link} href/with-classname With className /Link该故事用于验证next/link的 className 透传行为同时也是storybook/nextjs内部 CI 覆盖 CSS Modules 管线的用例之一。这印证了第二节所述的modules: { auto: true }getCssModuleLocalIdent管线在真实构建中可用。四、与 Next.js 其他样式方案的关系CSS Modules 只是 Next.js 样式矩阵中的一环。在同一文档章节nextjs.mdx「Next.js styling」中Storybook 对相邻方案的承诺可以帮你建立完整的选型认知全部同样零配置方案用法要点实现/出处全局 Sass/Scss在 preview 配置文件中导入如import ../styles/globals.scss自动继承next.config中的自定义 Sass 配置nextjs-styling-sass-preview.md、nextjs-styling-sass-config.mdCSS/Sass/Scss Modulesimport styles from ./X.module.(css\|scss\|sass)本文主题nextjs-styling-css-modules.mdStyled JSXNext.js 内置 CSS-in-JS零配置支持nextjs-styling-styled-jsx-component.mdTailwind通过 PostCSS 支持Storybook 自动接管 PostCSS 配置全局 CSS 直接在 preview 中导入nextjs-styling-tailwind.md内容为import ../app/globals.cssPostCSS自动处理你在 Next.js 中自定义的 PostCSS 配置css/webpack.ts 中postcss-loader全局样式与模块化样式的分工是.module.*文件随组件被引入、类名局部化而globals.css之类的全局文件则需要在 preview 层显式导入一次供所有故事共享。Tailwind 的 snippet 恰好演示了后者import ../app/globals.css;五、使用注意事项与适用边界类名哈希一致性由于getLocalIdent直接复用 Next.js 的实现CSS Modules 类名在 Storybook 与 Next.js 应用间保持一致如果你依赖类名做 DOM 断言如交互测试可以放心跨环境复用选择器。Sass 变体无需切换语法.module.scssSCSS 语法与.module.sass缩进语法走同一条sass-loader管线next.config中的sassOptions对两者同时生效。target.css例外Next.js 内部转成的target.css字体文件被显式排除在 css-loader 之外见 css/webpack.ts 第 44 行 注释你不需要也不应该手动 import 这类文件。绝对导入文档的「Imports → Absolute imports」一节确认从项目根目录的绝对路径导入 CSS Modules 同样可用例如import styles from styles/HomePage.module.css见 nextjs.mdx「Absolute imports」。适用前提上述结论基于仓库中storybook/nextjs框架包的实现code/frameworks/nextjs。该包同时覆盖 webpack 构建路径使用storybook/nextjs-vite时文档给出相同的 CSS Modules 承诺nextjs-vite.mdx 第 357-361 行但其底层走 Vite 的 CSS 管线具体 loader 细节与本文 webpack 版不同请以对应框架的实际行为为准。六、小结在storybook/nextjs项目中Button.module.css/.module.scss/.module.sass的默认导入无需任何 Storybook 配置即可工作组件内className{styles.error}的写法与应用端一致。其底层由 configureCss 实现style-loader css-loader(modules.auto: true, Next 官方 getLocalIdent) postcss-loader处理 CSS另加resolve-url-loader sass-loader透传nextConfig.sassOptions处理 Sass/Scss且url()/import解析复用 Next.js 官方的cssFileResolve。你的next.config会被 resolveNextConfig 加载并透传给整条 CSS 管线因此样式行为与 Next.js 应用保持一致。框架包内置故事 Link.stories.tsx 提供了.module.css的真实使用与测试用例可作为写法与断言的参照。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考