You need to enable JavaScript to run this app. Next.js项目中配置Storybook Webpack支持CSS模块绝对图片路径引用
优惠活动
大模型
产品
解决方案
定价
更多

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/下的实际资源,最终触发解析失败。

有效解决步骤
  1. 打开Storybook自定义配置文件(一般为项目根目录下的.storybook/main.js或.storybook/main.ts)
  2. 在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;
  },
};
  1. 确认css-loader配置开启了url资源解析(默认开启,若之前调试修改过需恢复默认),保证样式中的url()语法会被正常遍历解析。

配置完成后重启Storybook,即可正常识别public目录下的绝对路径图片资源,构建流程可顺利完成。


内容的提问来源于stack exchange,提问作者gdvander

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.17 19:45:08