Next13+Tailwind+Storybook7环境下本地字体无法加载问题

核心问题定位 #

CSS变量已生效但字体仍显示fallback，说明Storybook未正确读取或解析本地字体文件路径，而非样式变量问题。

分步修复方案 #

1. 确认字体声明路径正确性 #

检查globals.css中的字体声明，确保路径基于public文件夹的根路径：

/* globals.css 示例 */
@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/CustomFont-Regular.woff2') format('woff2'),
       url('/fonts/CustomFont-Regular.woff') format('woff');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

• 字体文件必须放在public/fonts（或自定义子目录）下，路径开头的/对应项目根目录的public文件夹。

2. 强制Storybook加载全局样式并模拟根结构 #

在.storybook/preview.ts中，确保全局CSS导入正确，并用Next.js的根标签包裹组件：

// .storybook/preview.ts
import type { Preview } from '@storybook/react';
import '../app/globals.css';
import { AppRouterCacheProvider } from 'next/dist/client/components/app-router-cache';

const preview: Preview = {
  decorators: [
    (Story) => (
      <AppRouterCacheProvider>
        <html lang="zh-CN">
          <body className="font-custom">
            <Story />
          </body>
        </html>
      </AppRouterCacheProvider>
    ),
  ],
};

export default preview;

• 用html和body标签模拟Next.js的根DOM结构，确保字体样式能作用到全局。

3. 配置Storybook静态资源目录 #

在.storybook/main.ts中添加staticDirs，明确指定public为静态资源目录：

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: ['../**/*.mdx', '../**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  framework: { name: '@storybook/nextjs', options: {} },
  staticDirs: ['../public'], // 关键配置：让Storybook识别public下的静态资源
};
export default config;

4. 验证Tailwind字体配置 #

检查tailwind.config.js中是否正确映射自定义字体：

// tailwind.config.js
module.exports = {
  content: ['./app/**/*.{js,ts,jsx,tsx,mdx}'],
  theme: {
    extend: {
      fontFamily: {
        custom: ['CustomFont', 'sans-serif'], // 与@font-face的font-family一致
      },
    },
  },
};

5. 清除缓存重试 #

• 删除.storybook/.next文件夹，重启Storybook清除缓存
• 开启浏览器开发者工具的「禁用缓存」选项，刷新页面验证

关键验证步骤 #

打开浏览器开发者工具的「网络」标签，搜索字体文件名：

• 若返回404：检查路径配置和staticDirs是否生效
• 若返回200但未应用：检查元素的font-family是否正确绑定了自定义字体类名

内容的提问来源于stack exchange，提问作者Dawid Dahl