如何通过cPanel自托管启用App Router的Next.js 13.4

一、基础配置确认 #

确保你的next.config.js正确配置独立构建模式：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
  // 13.4+ 版本默认启用App Router，若使用更早的13.x版本需添加：
  // experimental: { appDir: true },
};

module.exports = nextConfig;

二、构建与部署步骤 #

1. 本地完成项目构建
   运行构建命令生成独立部署包：

   npm run build
   # 或 yarn build / pnpm build
   

   构建完成后，项目根目录会生成以下关键目录：

   • .next/standalone：可独立运行的Node.js服务代码
   • .next/static：静态资源文件（CSS、JS、图片等）
   • public：项目公共静态资源

2. 服务器部署
   将上述三个目录同步到目标服务器的同一目录下（比如/opt/next-app），然后进入standalone目录启动服务：

   cd /opt/next-app/standalone
   # 默认端口3000，自定义端口可设置PORT环境变量
   PORT=3000 node server.js
   

三、常见问题排查（针对standalone模式运行失败） #

• Node.js版本不兼容：Next.js 13.4要求Node.js 16.8以上，推荐使用18.x LTS版本，版本过低会导致运行报错
• 静态资源路径错误：必须保证.next/static和public与standalone目录同级，否则会出现静态资源加载失败
• 环境变量缺失：服务器需配置NODE_ENV=production，若项目依赖其他环境变量（如API密钥、数据库连接串），需一并设置
• 端口占用：检查服务器3000端口是否被其他进程占用，可通过lsof -i :3000查看，或更换自定义端口
• 禁止修改自动生成的server.js：standalone模式下的server.js是Next.js自动生成的适配代码，手动修改会破坏兼容性，直接使用原始文件即可

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