前言

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

一、環(huán)境準(zhǔn)備

1.1 安裝 Node.js

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

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

1.2 創(chuàng)建全局軟鏈接（重要?。?/h3>

寶塔安裝的 Node.js 默認(rèn)不在系統(tǒng) PATH 中，會(huì)導(dǎo)致各種 command not found 錯(cuò)誤。

查找 Node.js 安裝路徑：

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

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

創(chuàng)建軟鏈接：

# 根據(jù)上面查到的路徑修改版本號(hào)
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

# 驗(yàn)證安裝
node -v
npm -v
pnpm -v

二、上傳項(xiàng)目代碼

2.1 正確的上傳方式

? 正確做法： 只上傳源代碼文件，不上傳 node_modules

需要上傳的文件：

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

? 錯(cuò)誤做法： 直接復(fù)制本地的 node_modules 到服務(wù)器

原因：

1. 平臺(tái)差異：Windows 和 Linux 的二進(jìn)制依賴不兼容
2. 符號(hào)鏈接失效：pnpm 使用硬鏈接/符號(hào)鏈接管理依賴，復(fù)制后會(huì)失效
3. 路徑問題：某些包會(huì)記錄絕對(duì)路徑，復(fù)制后路徑錯(cuò)誤

2.2 推薦的上傳方式

• Git 拉取（推薦）：服務(wù)器上直接 git clone 或 git pull
• 寶塔文件管理：打包源代碼為 zip，上傳后解壓
• SFTP/FTP：使用工具上傳源代碼文件

三、安裝依賴并構(gòu)建

3.1 進(jìn)入項(xiàng)目目錄

cd /www/wwwroot/你的項(xiàng)目目錄

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 構(gòu)建項(xiàng)目

npm run build
# 或
pnpm build

構(gòu)建成功后會(huì)生成 .next 目錄。

四、啟動(dòng)項(xiàng)目

4.1 命令行啟動(dòng)（測(cè)試用）

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

4.2 使用 PM2 管理器啟動(dòng)（推薦）

在寶塔面板安裝 PM2管理器，然后添加項(xiàng)目：

注意：添加項(xiàng)目前必須先手動(dòng)完成 npm install 和 npm run build

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

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

五、配置域名訪問

5.1 放行端口

在寶塔面板 安全 → 防火墻 中放行項(xiàng)目端口（如 3004）。

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

5.2 配置反向代理（推薦）

如果想通過域名 + 80/443 端口訪問，可以配置 Nginx 反向代理：

1. 在寶塔面板添加站點(diǎn)，綁定域名
2. 進(jìn)入站點(diǎn)設(shè)置 → 反向代理 → 添加反向代理
3. 配置如下：

4. 可選：配置 SSL 證書啟用 HTTPS

六、常見錯(cuò)誤及解決方案

6.1next: command not found

原因：依賴未安裝或安裝不完整

解決：

rm -rf node_modules
npm install

6.2Cannot find module 'xxx'

原因：node_modules 不完整，通常是直接復(fù)制導(dǎo)致

解決：

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. 確認(rèn)已在寶塔安裝 Node.js 版本管理器
2. 創(chuàng)建軟鏈接（見 1.2 節(jié)）

6.5EACCES: permission denied

原因：權(quán)限不足

解決：

sudo npm install
# 或修改目錄權(quán)限
chown -R www:www /www/wwwroot/你的項(xiàng)目目錄

6.6 構(gòu)建時(shí)內(nèi)存不足

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

解決：

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

或在本地構(gòu)建后上傳 .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. 進(jìn)入項(xiàng)目目錄
cd /www/wwwroot/你的項(xiàng)目目錄

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

# 4. 安裝依賴
npm install
# 或 pnpm install

# 5. 構(gòu)建
npm run build
# 或 pnpm build

# 6. 啟動(dòng)（測(cè)試）
npm run start

# 7. 使用 PM2 管理（生產(chǎn)環(huán)境）
# 在寶塔 PM2 管理器中添加項(xiàng)目

八、更新部署

項(xiàng)目代碼更新后，重新部署流程：

cd /www/wwwroot/你的項(xiàng)目目錄

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

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

# 重新構(gòu)建
npm run build

# 重啟項(xiàng)目（在 PM2 管理器中點(diǎn)擊重啟）

總結(jié)

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

最新評(píng)論