Next.js 14中next/image组件在Storybook无法加载的问题

问题分析 #

你遇到的核心问题是：Storybook的Next.js插件对next/image的资源解析逻辑和Next.js本身不一致，同时你尝试添加的image配置选项在当前插件版本中不存在，导致类型错误。

解决方案 #

1. 升级Storybook Next.js插件到最新版本

image配置选项是较新版本的@storybook/nextjs才引入的，旧版本没有对应的类型定义。执行以下命令升级：

npm install @storybook/nextjs@latest --save-dev
# 或使用yarn
yarn add @storybook/nextjs@latest --dev
# 或使用pnpm
pnpm add @storybook/nextjs@latest -D

2. 配置Storybook静态资源目录

Storybook默认不会自动识别Next.js的public目录资源，需要在.storybook/main.ts中添加staticDirs配置，让Storybook加载你的静态资源：

import type { StorybookConfig } from "@storybook/nextjs";
import * as path from "path";

const config: StorybookConfig = {
  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-onboarding",
    "@storybook/addon-interactions",
  ],
  // 添加静态资源目录配置
  staticDirs: ["../public"],
  framework: {
    name: "@storybook/nextjs",
    options: {
      nextConfigPath: path.resolve(__dirname, "../next.config.js"),
      builder: {
        useSWC: true,
      },
      // 升级后可正确添加image配置
      image: {
        loading: "eager",
      },
    },
  },
  docs: {
    autodocs: "tag",
  },
};
export default config;

3. 备选方案：Mock next/image组件（升级后仍有问题时使用）

如果升级插件后问题仍存在，可以在Storybook中mocknext/image，替换为适配的原生组件：
创建.storybook/preview.tsx文件，添加以下内容：

import type { Preview } from "@storybook/react";
import * as NextImage from "next/image";

// Mock next/image组件
const OriginalNextImage = NextImage.default;

Object.defineProperty(NextImage, "default", {
  configurable: true,
  value: (props: any) => <OriginalNextImage {...props} unoptimized />,
});

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: "^on[A-Z].*" },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};

export default preview;

添加unoptimized属性可让next/image以原生img的方式加载，避免Storybook的优化逻辑冲突。

验证 #

修改配置后重启Storybook服务，/app-New.svg图片即可正常加载。

内容的提问来源于stack exchange，提问作者Avishka Indula