配置Nuxt 3在Nginx反向代理下运行的问题排查

核心问题 #

你的配置错误在于Nuxt 3 未知晓自身运行在 /leaf 子路径下，导致生成的资源、路由路径均以根路径（/）开头，而 Nginx 未将这些根路径请求转发到 Nuxt 服务器，从而引发后续资源加载404/500错误。后端正常是因为其请求路径明确匹配了 /leaf/api/ 规则。

修复步骤 #

1. 修改 Nuxt 配置，指定子路径基础地址 #

在 nuxt.config.ts 中添加 base 配置，让 Nuxt 生成所有资源、路由时自动带上 /leaf 前缀：

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  sourcemap: {
    server: true,
    client: true
  },
  ssr: false,
  // 添加以下核心配置
  base: '/leaf/', // 指定应用的基础路径
  app: {
    baseURL: '/leaf/' // 确保路由生成时自动带上子路径前缀
  },

  css: [
    'primevue/resources/themes/saga-blue/theme.css',
    'primevue/resources/primevue.css',
    'primeicons/primeicons.css',
    'primeflex/primeflex.css',
    '/assets/styles/layout.scss'
  ],
  build: {
    transpile: ['primevue', 'primeflex']
  },
  modules: [
    '@pinia/nuxt',
    '@pinia-plugin-persistedstate/nuxt',
  ],
  vite: {
    build: {
      sourcemap: 'inline'
    },
  },
})

• 开发环境运行时，需添加参数适配子路径：nuxt dev --base /leaf/
• 生产构建后，产物中的资源路径会自动变为 /leaf/_nuxt/xxx 格式，完美适配代理规则。

2. 调整 Nginx 配置，适配 SPA 路由 #

修改 nginx.conf 中的 /leaf/ 规则，添加 SPA 路由 fallback 逻辑，确保所有 /leaf 下的路由请求都能被 Nuxt 处理：

location /leaf/api/ {
  proxy_pass http://localhost:8000/;
  proxy_set_header Host $http_host;
  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;
}

location /leaf/ {
  proxy_pass http://localhost:3000/;
  proxy_set_header Host $http_host;
  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;
  # SPA 路由 fallback：如果请求的文件/路径不存在，转发到 Nuxt 入口文件
  try_files $uri $uri/ /leaf/index.html;
}

location / {
  root   html;
  index  index.html index.htm;
}

关键说明 #

• proxy_pass 末尾的斜杠：/leaf/ 匹配的请求会去掉 /leaf/ 前缀后转发到 http://localhost:3000/，与 Nuxt 的 base 配置完全匹配，确保路径正确。
• try_files 指令：针对 SPA 单页应用，当用户直接访问 /leaf/some-page 这类路由时，Nginx 会将请求转发到 Nuxt 的入口文件，由前端路由处理，避免出现404。

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