Next.js静态HTML导出：资源路径失效（CSS、自定义字体、图片）

针对你用next build && next export生成静态文件后，CSS、图片、自定义字体路径错误的问题，以下是官方推荐且有效的解决步骤：

1. 完善next.config.js核心配置 #

Next.js 13+ 官方推荐用output: 'export'替代手动执行next export，同时配合assetPrefix和图片优化关闭配置，能统一大部分资源的路径：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 启用静态导出模式（替代 next build && next export 的手动命令）
  output: 'export',
  // 设置资源前缀为相对路径，适配本地打开静态文件的场景
  assetPrefix: './',
  // 静态导出时必须关闭图片优化，否则图片路径会异常
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

配置后，CSS的路径问题会被解决，同时为图片和字体的路径适配打下基础。

2. 图片路径的正确处理 #

无需手动写环境变量判断路径，通过以下两种方式自动适配开发/生产环境：

• 使用Next.js Image组件：配合上面的images.unoptimized: true配置，组件会自动生成正确的相对路径：

  import Image from 'next/image';
  
  export default function Home() {
    return (
      <Image
        src="/vercel.svg"
        alt="Vercel Logo"
        width={100}
        height={100}
      />
    );
  }
  

• 直接import图片文件：Webpack会自动处理路径，开发和导出时都能正常识别：

  import vercelLogo from '../public/vercel.svg';
  
  export default function Home() {
    return <img src={vercelLogo} alt="Vercel Logo" />;
  }
  

3. 自定义字体的路径适配 #

推荐用Next.js官方的next/font模块处理字体，它会自动处理路径、缓存和导出适配，无需手动调整路径：

本地自定义字体示例： #

// pages/index.js
import localFont from 'next/font/local';

// 加载本地字体文件（路径相对于当前文件）
const customFont = localFont({
  src: '../public/fonts/custom-font.woff2',
  // 定义CSS变量，方便全局使用
  variable: '--font-custom',
});

export default function Home() {
  return (
    // 挂载字体变量到根元素
    <div className={customFont.variable}>
      <p style={{ fontFamily: 'var(--font-custom)' }}>这是自定义字体的文字</p>
    </div>
  );
}

如果坚持用原生CSS引入字体，确保路径是相对public目录的相对路径，配合assetPrefix: './'会自动编译为正确的相对路径：

@font-face {
  font-family: 'CustomFont';
  src: url('./fonts/custom-font.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
}

关于assetPrefix的有效性 #

assetPrefix: './'是官方推荐的静态导出路径配置，之前只解决CSS问题是因为图片和字体的配套配置没跟上。配合上面的图片、字体处理方式后，所有资源路径都能正常适配本地打开静态文件的场景。

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