修改Next.js应用basePath后本地正常生产环境崩溃求助

1. next.config.js 核心配置错误 #

你写了两个独立的module.exports，Node.js会仅加载最后一个，导致第一个包含basePath的配置被完全覆盖——这是生产环境basePath未生效的根本原因，静态资源（CSS、JS）仍按根路径生成，Nginx无法匹配到资源，最终引发CSS丢失。

正确的合并配置写法：

module.exports = {
  basePath: "/custom-subpath",
  async redirects() {
    return [
      {
        source: "/",
        destination: "/custom-subpath/",
        permanent: true,
      },
    ];
  },
  publicRuntimeConfig: {
    basePath: process.env.NEXT_PUBLIC_BASE_PATH || "/custom-subpath"
  }
};

注意：basePath不要加结尾斜杠，Next.js会自动处理路径拼接逻辑。

2. 页面目录结构冗余操作 #

设置basePath后，不需要将pages下的文件移动到custom-subpath子目录，也无需重命名index.js。basePath是给整个应用添加全局路径前缀，原pages/index.js会自动对应/custom-subpath/，pages/page1.js自动对应/custom-subpath/page1。

你手动移动页面到子目录的操作，会导致路由变成/custom-subpath/custom-subpath/page1，与预期路径不符，进而引发导航跳转失败。

修复方式：

• 将custom-subpath子目录中的页面移回pages根目录
• 把重命名的custom-subpath.js改回index.js

3. 路由跳转写法错误 #

设置basePath后，使用Link组件或href时，无需手动添加custom-subpath前缀，Next.js会自动根据配置拼接路径。比如原href="page1"保持不变，会自动生成/custom-subpath/page1。

你现在手动写href="custom-subpath/page1"，会导致最终路径变成/custom-subpath/custom-subpath/page1，这就是登录按钮无法跳转的直接原因。

4. Nginx配置需适配basePath #

生产环境Nginx要正确配置反向代理，确保所有带/custom-subpath的请求转发给Next.js服务，同时正确映射静态资源路径。示例配置如下：

server {
  listen 80;
  server_name your-domain.com;

  location /custom-subpath {
    proxy_pass http://nextjs:3000; # 替换为你的Docker容器名/服务地址
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  # 静态资源直接托管配置（若挂载了.next目录）
  location /custom-subpath/_next/static {
    alias /path/to/your/next/app/.next/static;
    expires 365d;
    access_log off;
  }
}

本地正常、生产出错的原因 #

本地开发服务器（next dev）会实时解析配置，部分错误会被开发模式兼容；但生产环境是构建后的静态资源（next build），配置错误会直接导致资源路径生成异常，再加上Nginx路径映射未适配，就出现了CSS丢失、跳转失败的问题。

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