Next-auth 4与REST API路由冲突，如何自定义认证路由（不改basePath）

问题 #

我有一个已上线的PHP/Nginx公共REST API，地址为https://example.com/api/...。现在要开发带认证功能的GUI管理API资源，GUI通过https://example.com访问，选用Next.js和next-auth 4。

next-auth 4默认使用/api/auth/*路由，本地运行正常，但部署后点击登录跳转至https://example.com/api/auth/error时，返回现有REST API的错误输出——因为Web服务器配置将所有/api请求转发至PHP API入口。

我不想修改Kubernetes集群的Web服务器配置（用helmfile、helmcharts，配置复杂），希望自定义next-auth的默认认证路由。尝试过basePath功能但仅获404错误，该功能仅适用于UI部署在子路径的场景，不符合需求。

曾将pages/api移至pages/foo/api，页面刷新时出现GET http://localhost:3000/api/auth/session 404 (Not Found)错误，因为next-auth默认期望api目录位于pages/下。

请问是否存在无需修改basePath即可自定义next-auth的/api/auth/*路径的方法？

解决方案 #

完全可以通过自定义next-auth的路由文件位置+配置参数实现，无需修改Web服务器配置或全局basePath，具体步骤如下：

1. 迁移认证路由文件到自定义路径
   把原pages/api/auth/[...nextauth].js文件移动到你想要的自定义路径下，比如pages/portal/auth/[...nextauth].js。此时next-auth的认证路由会变成/portal/auth/*，彻底避开被PHP占用的/api前缀。

2. 配置next-auth服务端路径
   在新的[...nextauth].js文件中，初始化NextAuth时添加path参数指定自定义路由前缀：

   import NextAuth from "next-auth"
   import Providers from "next-auth/providers"
   
   export default NextAuth({
     providers: [
       // 你的认证提供者配置
     ],
     path: "/portal/auth", // 填写自定义路由前缀
     // 其他配置项...
   })
   

3. 配置客户端使用自定义路径
   在客户端使用next-auth的钩子或跳转方法时，需要指定自定义的base路径：

   • 如果使用SessionProvider（通常在_app.js中），添加basePath属性：

     import { SessionProvider } from "next-auth/react"
     
     function MyApp({ Component, pageProps }) {
       return (
         <SessionProvider basePath="/portal/auth" session={pageProps.session}>
           <Component {...pageProps} />
         </SessionProvider>
       )
     }
     
     export default MyApp
     

   • 直接调用signIn/signOut时，可通过basePath参数指定：

     import { signIn } from "next-auth/react"
     
     signIn("credentials", {
       basePath: "/portal/auth",
       // 其他参数...
     })
     

4. 设置正确的环境变量
   确保NEXTAUTH_URL环境变量设置为自定义路由的完整地址，比如https://example.com/portal/auth，避免认证回调时出现地址不匹配的错误。

关键说明 #

之前移动pages/api到pages/foo/api后出现404，是因为只修改了文件位置，但没有告诉next-auth服务端和客户端使用新的路由路径，导致客户端仍然默认请求/api/auth/session，自然找不到对应的接口。

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