Next.js部署至Vercel时本地字体无法解析问题求助

问题原因总结 #

1. 大小写敏感差异：本地开发环境（Windows/macOS）默认大小写不敏感，但Vercel的Linux服务器严格区分大小写，文件名拼写不一致会导致构建时找不到文件。
2. jsconfig路径配置错误：baseUrl设为src后，paths映射重复添加了src前缀，导致构建阶段路径解析混乱。
3. public文件夹使用误区：next/font/local无需将字体放入public目录，该API会自动从源码目录打包优化字体，放入public反而会引发路径解析错误。

分步解决方案 #

1. 恢复字体文件位置 #

将字体放回src/styles/fonts目录，保持初始文件夹结构：

src
├── _app.js
└── styles
    ├── font.js
    └── fonts
        ├── BrFirma-Regular.woff2
        └── BrFirma-SemiBold.woff2

2. 确认font.js的字体路径 #

确保路径是相对于font.js的正确相对路径（初始代码无需修改）：

import localFont from 'next/font/local';

export const BRFirma = localFont({
    src: [
        {
            path: './fonts/BrFirma-Regular.woff2',
            weight: '400',
        },
        {
            path: './fonts/BrFirma-SemiBold.woff2',
            weight: '600',
        },
    ],
}); 

3. 修复jsconfig.js的路径配置 #

baseUrl已设为src，@/*应直接映射到./（即src目录下的所有文件），避免路径重复：

{
    "compilerOptions": {
        "baseUrl": "src",
        "paths": {
            "@/*": ["./*"]
        }
    },
    "exclude": ["node_modules", "build", "dist", "jest"]
}

4. 严格校验文件名大小写 #

重点检查代码中引用的字体文件名和实际文件的大小写完全一致（比如BrFirma-Regular.woff2不能写成brfirma-regular.woff2），这是Vercel部署时常见的触发点。

5. 优化导入方式（可选） #

在_app.js中使用别名导入，避免相对路径的潜在问题：

import { BRFirma } from '@/styles/font';

export default function App({ Component, pageProps }) {
  return (
    <main className={BRFirma.className}>
      <Component {...pageProps} />
    </main>
  );
}

额外注意事项 #

• 不要将next/font/local处理的字体放入public目录，该API的设计逻辑是从源码目录导入字体，Next.js会自动完成预加载、缓存和优化。
• 若问题仍存在，可尝试清除本地缓存（执行rm -rf .next）后重新构建，再部署到Vercel。

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