Next.js静态构建后本地打开HTML的CSS/JS路径问题求助

问题 #

用Next.js执行静态构建（配置output: 'export'）后，将产物下载到本地直接打开HTML文件时，CSS、JS等资源的路径以file:///开头，导致无法正常加载。尝试设置assetPrefix: "./"或basePath: "./"，但Next.js报错，要求路径必须以/开头。当前next.config.js配置如下：

/** @type {import('next').NextConfig} */
const path = require('path');
const nextConfig = {
  output: 'export',
  reactStrictMode: false,
  images: {
    loader: "custom",
    loaderFile: "localImageLoader.js"
  },
  webpack(config, options) {
    config.resolve.modules.push(path.resolve("./"));

    return config;
  },
}

module.exports = nextConfig

解决办法 #

方法1：通过Webpack替换资源路径为相对路径 #

Next.js的assetPrefix要求路径以/开头，我们可以先设置临时的绝对路径，再通过Webpack将所有资源路径替换为相对路径：
修改next.config.js如下：

/** @type {import('next').NextConfig} */
const path = require('path');
const nextConfig = {
  output: 'export',
  reactStrictMode: false,
  images: {
    loader: "custom",
    loaderFile: "localImageLoader.js"
  },
  // 先设置临时绝对路径，后续Webpack会替换
  assetPrefix: '/',
  webpack(config, options) {
    config.resolve.modules.push(path.resolve("./"));

    if (!options.isServer) {
      // 输出资源时使用相对路径
      config.output.publicPath = './';
      // 替换所有/_next/开头的路径为./_next/
      config.module.rules.push({
        test: /\.(css|js|html)$/,
        use: [{
          loader: 'string-replace-loader',
          options: {
            search: '/_next/',
            replace: './_next/',
            flags: 'g'
          }
        }]
      });
    }

    return config;
  },
}

module.exports = nextConfig

执行前需要安装依赖：

npm install string-replace-loader --save-dev

方法2：用本地静态服务访问（推荐） #

如果不需要直接打开本地HTML文件，而是通过本地服务访问，可以设置合法的basePath，再用静态服务启动：
修改next.config.js：

/** @type {import('next').NextConfig} */
const path = require('path');
const nextConfig = {
  output: 'export',
  reactStrictMode: false,
  images: {
    loader: "custom",
    loaderFile: "localImageLoader.js"
  },
  // 设置以/开头的basePath，对应本地服务的访问路径
  basePath: '/my-static-site',
  webpack(config, options) {
    config.resolve.modules.push(path.resolve("./"));

    return config;
  },
}

module.exports = nextConfig

构建完成后，用serve启动本地服务：

npm install -g serve
serve out

访问http://localhost:3000/my-static-site即可正常加载所有资源。

方法3：自定义HTML模板手动修改路径 #

创建（或修改）pages/_document.js，手动将资源路径改为相对路径：

import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head>
        {/* 手动指定CSS相对路径 */}
        <link rel="stylesheet" href="./_next/static/css/styles.css" />
      </Head>
      <body>
        <Main />
        {/* 手动指定JS相对路径 */}
        <NextScript src="./_next/static/chunks/main.js" />
      </body>
    </Html>
  );
}

注意：这种方法需要手动匹配构建后的实际资源文件名，适合结构简单的小型项目，否则容易遗漏动态加载的资源。

内容的提问来源于stack exchange，提问作者서보경