NextJS basePath在CSS url()中不生效，如何修正路径？

问题原因 #

NextJS 的 basePath 和 assetPrefix 配置不会自动处理 CSS 文件中硬编码的绝对路径（如 /images/paper-light.png），仅对 JSX 中通过 next/image 组件、publicRuntimeConfig 注入的路径生效。

修复方案 #

方案一：使用 CSS 变量动态注入 basePath

1. 在 _app.js 中根据环境设置全局 CSS 变量

import { useEffect } from 'react';

export default function MyApp({ Component, pageProps }) {
  useEffect(() => {
    const basePath = process.env.NODE_ENV === 'production' ? '/blog' : '';
    document.documentElement.style.setProperty('--base-path', basePath);
  }, []);

  return <Component {...pageProps} />;
}

2. 修改 global.css 中的背景图路径，使用 CSS 变量

body {
  background-image: url(var(--base-path)/images/paper-light.png);
}

方案二：通过 publicRuntimeConfig 动态设置样式

1. 更新 next.config.js，添加 publicRuntimeConfig 配置

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  publicRuntimeConfig: {
    basePath: process.env.NODE_ENV === 'production' ? '/blog' : '',
  },
};

if (process.env.NODE_ENV === 'production') {
  nextConfig.basePath = '/blog';
  nextConfig.assetPrefix = '/blog';
}

module.exports = nextConfig;

2. 在 _app.js 中读取配置并设置背景图

import getConfig from 'next/config';
import { useEffect } from 'react';

const { publicRuntimeConfig } = getConfig();

export default function MyApp({ Component, pageProps }) {
  useEffect(() => {
    document.body.style.backgroundImage = `url(${publicRuntimeConfig.basePath}/images/paper-light.png)`;
  }, []);

  return <Component {...pageProps} />;
}

之后可移除 global.css 中对应的 background-image 配置。

方案三：硬编码环境区分（不推荐）

直接为不同环境编写对应样式，灵活性差，仅适合简单场景：

/* 开发环境 */
body {
  background-image: url('/images/paper-light.png');
}

/* 生产环境 */
@media (min-width: 0px) {
  body {
    background-image: url('/blog/images/paper-light.png');
  }
}

推荐方案 #

优先选择 方案一 或 方案二，二者均能根据环境动态适配路径，避免硬编码维护成本。

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