如何在GoDaddy cPanel共享主机部署Next.js应用？

一、先解决npm install终止的核心问题 #

npm install中断是因为共享主机资源有限或缓存异常，按以下步骤操作：

1. 清理npm缓存：

   npm cache clean --force
   

2. 用精简参数重新安装，减少资源占用：

   npm install --no-audit --no-fund
   

3. 确认Node.js版本和本地开发环境一致：
   • 本地执行node -v查看版本
   • 服务器终端用nvm use [你的版本号]切换，比如nvm use 18.17.0（Next.js 13+要求Node.js≥18.17.0）
4. 上传代码时不要包含本地的node_modules文件夹，必须在服务器重新安装依赖。

二、修复npm start的"Cannot find module 'next'"错误 #

这个错误本质是依赖未安装成功，解决上面的npm install问题后，还需调整配置适配GoDaddy环境：

1. 修改server.js的hostname和port：
   • 将hostname: "localhost"改为你的域名（比如"example.com"）或cPanel分配的主机名
   • 确保port使用cPanel允许的端口，直接用process.env.PORT即可（GoDaddy会自动分配可用端口）
     修改后的核心代码：

   const dev = process.env.NODE_ENV !== "production";
   const hostname = "example.com"; // 替换为你的域名
   const port = process.env.PORT; // 直接用环境变量分配的端口
   

2. 验证依赖安装完成：
   执行ls node_modules，确认存在next文件夹，再运行npm start。

三、完整部署流程 #

1. 本地预构建：
   在本地项目根目录执行npm run build，生成.next构建文件夹，避免占用服务器资源。
2. 上传代码：
   将本地的.next、server.js、package.json、package-lock.json（或yarn.lock）以及Sanity配置文件（如sanity.config.js）上传到cPanel的目标目录（比如public_html/next-app）。
3. 配置环境变量：
   在cPanel的"环境变量"功能中添加Sanity的相关配置（如SANITY_PROJECT_ID、SANITY_API_TOKEN），不要直接上传.env文件到公开目录。
4. 后台运行应用：
   共享主机直接用npm start会在终端断开后停止，需用进程管理器守护：
   • 安装pm2：npm install pm2 -g
   • 启动应用：pm2 start server.js --name next-sanity-app
   • 设置开机自启：pm2 startup
   • 查看运行状态：pm2 status
5. 配置反向代理（Apache）：
   在public_html下创建.htaccess文件，将域名请求转发到Next.js的端口（替换XXXX为pm2显示的端口）：

   RewriteEngine On
   RewriteRule ^$ http://localhost:XXXX/ [P,L]
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule ^(.*)$ http://localhost:XXXX/$1 [P,L]
   

四、常见排查点 #

• 如果pm2启动后应用崩溃，查看日志：pm2 logs next-sanity-app
• 确认Sanity的API访问权限，确保服务器IP在Sanity的允许列表中（如果设置了IP白名单）
• 检查cPanel的防火墙设置，确保Next.js使用的端口未被封禁

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