Next.js 静态资源非根目录部署指南

问题背景

在使用 Next.js 开发的项目中，当需要将静态资源部署到非根目录（如 /s/web/）时，经常会遇到路由和资源加载的问题。本文将介绍如何正确配置 Next.js 和 Nginx 来解决这个问题。

Next.js 配置详解

首先，我们需要在 next.config.mjs 中进行以下配置：

const nextConfig = {
    output: 'export',        // 静态导出模式
    distDir: 'dist',         // 自定义构建输出目录
    basePath: '/s/web',      // 应用的基础路径
    assetPrefix: '/s/web',   // 静态资源前缀
    trailingSlash: false,    // 是否在URL末尾添加斜杠
}

配置说明：

• output: 'export'：将项目导出为静态HTML文件
• distDir: 'dist'：指定构建输出目录为 dist
• basePath：设置应用的基础路径，所有的页面路由都会基于此路径
• assetPrefix：设置静态资源（如JS、CSS、图片等）的访问前缀
• trailingSlash: false：URL末尾不添加斜杠，避免路由匹配问题

Nginx 配置说明

location /s/ {
    alias /data/appsystems/s/;
    try_files $uri $uri/index.html $uri.html $request_uri/index.html;
}

配置说明：

• alias 指定静态资源的实际存放目录
• try_files 定义了文件查找的顺序：
  1. 先查找完整路径 ($uri)
  2. 查找目录下的 index.html ($uri/index.html)
  3. 查找带 .html 后缀的文件 ($uri.html)
  4. 查找请求路径下的 index.html ($request_uri/index.html)

注意事项

1. basePath 和 assetPrefix 的值必须保持一致
2. 确保 Nginx 中的 alias 路径与实际部署目录对应
3. 在开发环境中可以根据环境变量动态设置这些值：

basePath: process.env.NEXT_PUBLIC_PATH,
assetPrefix: process.env.NEXT_PUBLIC_PATH,

常见问题排查

1. 静态资源404：检查 assetPrefix 配置是否正确
2. 路由无法访问：确认 basePath 配置和 Nginx try_files 配置是否正确
3. 刷新页面404：检查 Nginx 的 try_files 配置是否完整

总结

通过正确配置 Next.js 的 basePath 和 assetPrefix，再配合 Nginx 的路由规则，可以实现 Next.js 应用在非根目录下的完美部署。这个方案适用于需要在同一域名下部署多个应用的场景。

希望这篇文章能帮助大家解决 Next.js 非根目录部署的问题。如有任何疑问，欢迎讨论交流。