Next.js项目中配置Storybook Webpack支持CSS模块绝对图片路径引用
- 技术栈为Next.js + Ant Design + Less + TypeScript,正在为项目搭建适配的Storybook组件预览环境
- 遵循Next.js开发规范:所有静态图片资源统一存放于项目
public/目录下,全项目引用统一使用根路径绝对路径(如/images/cucumber.png) - 出现问题的样式代码(写在CSS模块中):
.testImage { background-image: url('/images/cucumber.png'); background-repeat: no-repeat; background-size: contain; height: 300px; width: 300px; }
执行Storybook启动命令时,webpack构建流程直接中断,抛出css-loader解析失败的错误:
核心报错内容:
ERROR in ./common/layout/TestImage/TestImage.module.css (./node_modules/css-loader/dist/cjs.js??ref--15-1!./common/layout/TestImage/TestImage.module.css)
Module build failed (from ./node_modules/css-loader/dist/cjs.js):
Error: Can't resolve '/images/cucumber.png' in '/Users/gerritvanderlugt/Development/misc/storybook-issue/common/layout/TestImage'
报错链路最终会追溯到stories文件的入口打包逻辑,无其他额外提示。
目前已尝试的排查操作:
- 单独调整
file-loader对图片格式的解析规则 - 单独调整
url-loader的资源基础路径、体积阈值配置 - 单独调整
css-loader的资源引用解析参数
以上操作均未解决构建失败的问题。
webpack默认逻辑里,以/开头的路径会被识别为服务部署后的运行时根路径,不会关联本地项目目录做文件映射。Next.js框架本身在内置构建流程中,已经增加了public/目录到根路径的映射逻辑,但Storybook启动时使用独立的webpack配置,未同步这套映射规则:当遇到样式里url('/xxx')的引用写法时,webpack会尝试从本地磁盘根目录寻找对应文件,自然无法匹配到项目public/下的实际资源,最终触发解析失败。
- 打开Storybook自定义配置文件(一般为项目根目录下的
.storybook/main.js或.storybook/main.ts) - 在
webpackFinal配置项中补充两项核心映射规则,完整配置参考如下:
const path = require('path'); module.exports = { // 保留原有Storybook配置(如stories路径、addon列表等) webpackFinal: async (config) => { // 配置路径别名:将根路径/ 映射到项目下的public目录 config.resolve.alias = { ...config.resolve.alias, '/': path.resolve(__dirname, '../public'), }; // 补充静态资源解析规则,让原有图片loader覆盖public目录 config.module.rules = config.module.rules.map((rule) => { // 匹配处理图片格式的webpack规则 if (rule.test && rule.test.toString().includes('png')) { return { ...rule, include: [ path.resolve(__dirname, '../public'), ...(rule.include || []), ], }; } return rule; }); return config; }, };
- 确认
css-loader配置开启了url资源解析(默认开启,若之前调试修改过需恢复默认),保证样式中的url()语法会被正常遍历解析。
配置完成后重启Storybook,即可正常识别public目录下的绝对路径图片资源,构建流程可顺利完成。
内容的提问来源于stack exchange,提问作者gdvander

