宝塔面板部署Next.js项目的完整流程及常见问题

前言

本文记录在宝塔面板（Linux 服务器）上部署 Next.js 项目的完整流程，以及常见问题的解决方案。

一、环境准备

1.1 安装 Node.js

登录宝塔面板，进入 软件商店，搜索并安装 Node.js版本管理器。

安装完成后，选择一个 Node.js 版本（推荐 18.x 或 20.x 或 22.x）。

1.2 创建全局软链接（重要！）

宝塔安装的 Node.js 默认不在系统 PATH 中，会导致各种 command not found 错误。

查找 Node.js 安装路径：

find /www -name "node" -type f 2>/dev/null

输出示例：/www/server/nodejs/v22.20.0/bin/node

创建软链接：

# 根据上面查到的路径修改版本号
NODE_PATH=/www/server/nodejs/v22.20.0/bin

# 创建 node 和 npm 软链接
ln -sf $NODE_PATH/node /usr/bin/node
ln -sf $NODE_PATH/npm /usr/bin/npm

# 安装 pnpm（可选）
$NODE_PATH/npm install -g pnpm
ln -sf $NODE_PATH/pnpm /usr/bin/pnpm

# 验证安装
node -v
npm -v
pnpm -v

二、上传项目代码

2.1 正确的上传方式

✅ 正确做法： 只上传源代码文件，不上传 node_modules

需要上传的文件：

• package.json
• package-lock.json 或 pnpm-lock.yaml（如果有）
• src/ 或 app/ 目录
• public/ 目录
• 配置文件（next.config.js、tailwind.config.js 等）
• 其他源代码文件

❌ 错误做法： 直接复制本地的 node_modules 到服务器

原因：

1. 平台差异：Windows 和 Linux 的二进制依赖不兼容
2. 符号链接失效：pnpm 使用硬链接/符号链接管理依赖，复制后会失效
3. 路径问题：某些包会记录绝对路径，复制后路径错误

2.2 推荐的上传方式

• Git 拉取（推荐）：服务器上直接 git clone 或 git pull
• 宝塔文件管理：打包源代码为 zip，上传后解压
• SFTP/FTP：使用工具上传源代码文件

三、安装依赖并构建

3.1 进入项目目录

cd /www/wwwroot/你的项目目录

3.2 清理旧依赖（如果有）

rm -rf node_modules
rm -f pnpm-lock.yaml package-lock.json yarn.lock

3.3 安装依赖

使用 npm：

npm install

或使用 pnpm（更快）：

pnpm install

3.4 构建项目

npm run build
# 或
pnpm build

构建成功后会生成 .next 目录。

四、启动项目

4.1 命令行启动（测试用）

npm run start
# 或指定端口
npm run start -- -p 3004

4.2 使用 PM2 管理器启动（推荐）

在宝塔面板安装 PM2管理器，然后添加项目：

注意：添加项目前必须先手动完成 npm install 和 npm run build

4.3 修改 package.json 指定端口（可选）

{
  "scripts": {
    "start": "next start -p 3004"
  }
}

五、配置域名访问

5.1 放行端口

在宝塔面板 安全 → 防火墙 中放行项目端口（如 3004）。

同时检查服务器厂商的安全组规则，确保端口已放行。

5.2 配置反向代理（推荐）

如果想通过域名 + 80/443 端口访问，可以配置 Nginx 反向代理：

1. 在宝塔面板添加站点，绑定域名
2. 进入站点设置 → 反向代理 → 添加反向代理
3. 配置如下：

4. 可选：配置 SSL 证书启用 HTTPS

六、常见错误及解决方案

6.1next: command not found

原因：依赖未安装或安装不完整

解决：

rm -rf node_modules
npm install

6.2Cannot find module 'xxx'

原因：node_modules 不完整，通常是直接复制导致

解决：

rm -rf node_modules
rm -f package-lock.json
npm install

6.3/usr/bin/env: 'node': No such file or directory

原因：Node.js 未添加到系统 PATH

解决：创建软链接（见 1.2 节）

6.4npm: command not found或pnpm: command not found

原因：Node.js 未安装或未创建软链接

解决：

1. 确认已在宝塔安装 Node.js 版本管理器
2. 创建软链接（见 1.2 节）

6.5EACCES: permission denied

原因：权限不足

解决：

sudo npm install
# 或修改目录权限
chown -R www:www /www/wwwroot/你的项目目录

6.6 构建时内存不足

原因：服务器内存较小，Next.js 构建消耗内存较大

解决：

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" npm run build

或在本地构建后上传 .next 目录（需要相同 Node.js 版本）。

七、完整部署流程清单

# 1. 创建软链接（首次部署需要）
NODE_PATH=/www/server/nodejs/v22.20.0/bin
ln -sf $NODE_PATH/node /usr/bin/node
ln -sf $NODE_PATH/npm /usr/bin/npm
$NODE_PATH/npm install -g pnpm
ln -sf $NODE_PATH/pnpm /usr/bin/pnpm

# 2. 进入项目目录
cd /www/wwwroot/你的项目目录

# 3. 清理旧依赖
rm -rf node_modules
rm -f package-lock.json pnpm-lock.yaml

# 4. 安装依赖
npm install
# 或 pnpm install

# 5. 构建
npm run build
# 或 pnpm build

# 6. 启动（测试）
npm run start

# 7. 使用 PM2 管理（生产环境）
# 在宝塔 PM2 管理器中添加项目

八、更新部署

项目代码更新后，重新部署流程：

cd /www/wwwroot/你的项目目录

# 拉取最新代码（如果用 Git）
git pull

# 安装新依赖（如果 package.json 有变化）
npm install

# 重新构建
npm run build

# 重启项目（在 PM2 管理器中点击重启）

总结

到此这篇关于宝塔面板部署Next.js项目的完整流程及常见问题的文章就介绍到这了,更多相关宝塔面板部署Next.js项目内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！