如何将基于app router的Next.js 14项目部署到cPanel并配置启动文件

一、本地项目打包 #

• 在本地项目根目录执行npm run build，生成.next构建产物文件夹。注意：因项目含动态内容，不可使用npm run export。
• 确认package.json中存在start命令，示例：

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
  

  无需指定端口，cPanel会自动分配并完成反向代理。

二、上传项目文件到cPanel #

• 登录cPanel，打开文件管理器，进入目标域名对应的根目录（如public_html或子域名专属目录）。
• 将以下本地文件/文件夹压缩为ZIP包后上传，再在cPanel内解压：
  • .next文件夹
  • package.json
  • package-lock.json（或yarn.lock）
  • public文件夹（含静态资源时）
  • .env.production（生产环境变量配置文件，含PHP API地址等）
• 不要上传node_modules，后续在cPanel内安装依赖。

三、安装项目依赖 #

• 打开cPanel的终端工具，切换到项目目录（示例：cd public_html/your-project-directory）。
• 执行npm install，等待依赖安装完成。若主机支持Yarn，也可使用yarn install。

四、配置cPanel Node.js应用 #

• 返回cPanel主页，找到Setup Node.js App工具，点击Create Application：
  • 基础配置：
    • Node.js版本：选择与本地开发一致的18.x/20.x版本（Next.js 14要求Node.js≥18.17）
    • Application mode：选择Production
    • Application root：填写项目所在的绝对路径（如public_html/your-project）
    • Application URL：选择部署对应的域名/子域名
    • Application startup file：填写node_modules/next/dist/bin/next（这是Next.js官方的启动入口，无需自定义server文件）
  • 点击Create完成应用创建。
• 在应用列表中找到你的项目，点击Start Application启动服务。若之前未安装依赖，可点击Run npm install触发安装。

五、PHP API适配配置 #

• 将PHP API文件上传到cPanel的合适目录（如项目根目录下的php-api文件夹），确保API接口可通过线上域名正常访问（例如https://your-domain.com/php-api/get-data.php）。
• 检查.env.production中的API地址配置，示例：

  NEXT_PUBLIC_API_URL=https://your-domain.com/php-api/
  

  确保Next.js项目调用API时使用该线上地址，避免跨域问题（同域名下无需额外配置CORS）。

六、常见问题排查 #

• 启动失败：查看cPanel的Error Logs或Setup Node.js App内的Logs面板，排查依赖缺失、环境变量错误等问题。
• 静态资源加载异常：确认public文件夹路径正确，Next.js会自动处理静态资源路由。
• 端口冲突：无需手动指定端口，cPanel会自动分配端口并反向代理到你的域名。

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