前言

本文記錄在寶塔面板（Linux 服務器）上部署 Next.js 項目的完整流程，以及常見問題的解決方案。

一、環(huán)境準備

1.1 安裝 Node.js

登錄寶塔面板，進入 軟件商店，搜索并安裝 Node.js版本管理器。

安裝完成后，選擇一個 Node.js 版本（推薦 18.x 或 20.x 或 22.x）。

1.2 創(chuàng)建全局軟鏈接（重要！）

寶塔安裝的 Node.js 默認不在系統(tǒng) PATH 中，會導致各種 command not found 錯誤。

查找 Node.js 安裝路徑：

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

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

創(chuàng)建軟鏈接：

# 根據(jù)上面查到的路徑修改版本號
NODE_PATH=/www/server/nodejs/v22.20.0/bin

# 創(chuàng)建 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）。

同時檢查服務器廠商的安全組規(guī)則，確保端口已放行。

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 未添加到系統(tǒng) PATH

解決：創(chuàng)建軟鏈接（見 1.2 節(jié)）

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

原因：Node.js 未安裝或未創(chuàng)建軟鏈接

解決：

1. 確認已在寶塔安裝 Node.js 版本管理器
2. 創(chuàng)建軟鏈接（見 1.2 節(jié)）

6.5EACCES: permission denied

原因：權限不足

解決：

sudo npm install
# 或修改目錄權限
chown -R www:www /www/wwwroot/你的項目目錄

6.6 構建時內(nèi)存不足

原因：服務器內(nèi)存較小，Next.js 構建消耗內(nèi)存較大

解決：

# 增加 Node.js 內(nèi)存限制
NODE_OPTIONS="--max-old-space-size=4096" npm run build

或在本地構建后上傳 .next 目錄（需要相同 Node.js 版本）。

七、完整部署流程清單

# 1. 創(chuàng)建軟鏈接（首次部署需要）
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 管理（生產(chǎn)環(huán)境）
# 在寶塔 PM2 管理器中添加項目

八、更新部署

項目代碼更新后，重新部署流程：

cd /www/wwwroot/你的項目目錄

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

# 安裝新依賴（如果 package.json 有變化）
npm install

# 重新構建
npm run build

# 重啟項目（在 PM2 管理器中點擊重啟）

總結

到此這篇關于寶塔面板部署Next.js項目的完整流程及常見問題的文章就介紹到這了,更多相關寶塔面板部署Next.js項目內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論