如何在运行时通过环境变量设置NextJS的assetPrefix？

核心限制说明 #

assetPrefix 是构建时配置项，Next.js 在构建阶段会把静态资源路径硬编码到生成的HTML、JS文件中，所以直接在next.config.js里用运行时环境变量行不通——构建时该变量还未赋值，或值与运行时不一致。

原生方案：运行时配置+自定义_document.tsx #

这是Next.js原生支持的方式，无需额外依赖：

1. 启用运行时配置 #

在next.config.js中添加experimental.runtimeEnv，将需要的环境变量暴露给客户端：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
  experimental: {
    runtimeEnv: {
      NEXT_PUBLIC_CDN_PREFIX: process.env.NEXT_PUBLIC_CDN_PREFIX,
    },
  },
};

module.exports = nextConfig;

2. 自定义_document.tsx覆盖静态资源前缀 #

_document.tsx是服务端渲染的入口文件，可在此动态修改静态资源前缀：

import { Html, Head, Main, NextScript } from 'next/document';
import { experimental_runtimeEnv } from 'next/dist/build/utils';

export default function Document() {
  const cdnPrefix = experimental_runtimeEnv.NEXT_PUBLIC_CDN_PREFIX || '';
  
  return (
    <Html>
      <Head>
        {/* 动态设置base标签，自动替换所有绝对路径的静态资源前缀 */}
        {cdnPrefix && <base href={`${cdnPrefix}/`} />}
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

注：若静态资源采用绝对路径（如/_next/static/...），base标签会自动将其替换为${cdnPrefix}/_next/static/...，覆盖绝大多数场景需求。

3. 兜底重写（可选） #

若存在Next.js自动生成的特殊资源路径，可在next.config.js中添加rewrites做兜底：

// next.config.js 追加配置
const nextConfig = {
  // ...其他配置
  async rewrites() {
    return [
      {
        source: '/_next/static/:path*',
        destination: `${process.env.NEXT_PUBLIC_CDN_PREFIX || ''}/_next/static/:path*`,
      },
    ];
  },
};

为什么不推荐中间件？ #

中间件仅能拦截请求并重定向，无法修改HTML中已硬编码的静态资源路径，效果远不如自定义_document.tsx直接。

验证步骤 #

1. 构建Docker镜像时，不设置NEXT_PUBLIC_CDN_PREFIX环境变量
2. 启动容器时，传入NEXT_PUBLIC_CDN_PREFIX=https://your-cdn-url
3. 查看页面源码，静态资源路径应已带上CDN前缀

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