宝塔面板部署Next.js项目的完整流程及常见问题
<div id="navCategory"><h5 class="catalogue">目录</h5><ul class="first_class_ul"><li><a href="#_label0">前言</a></li><li><a href="#_label1">一、环境准备</a></li><ul class="second_class_ul"><li><a href="#_lab2_1_0">1.1 安装 Node.js</a></li><li><a href="#_lab2_1_1">1.2 创建全局软链接（重要！）</a></li></ul><li><a href="#_label2">二、上传项目代码</a></li><ul class="second_class_ul"><li><a href="#_lab2_2_2">2.1 正确的上传方式</a></li><li><a href="#_lab2_2_3">2.2 推荐的上传方式</a></li></ul><li><a href="#_label3">三、安装依赖并构建</a></li><ul class="second_class_ul"><li><a href="#_lab2_3_4">3.1 进入项目目录</a></li><li><a href="#_lab2_3_5">3.2 清理旧依赖（如果有）</a></li><li><a href="#_lab2_3_6">3.3 安装依赖</a></li><li><a href="#_lab2_3_7">3.4 构建项目</a></li></ul><li><a href="#_label4">四、启动项目</a></li><ul class="second_class_ul"><li><a href="#_lab2_4_8">4.1 命令行启动（测试用）</a></li><li><a href="#_lab2_4_9">4.2 使用 PM2 管理器启动（推荐）</a></li><li><a href="#_lab2_4_10">4.3 修改 package.json 指定端口（可选）</a></li></ul><li><a href="#_label5">五、配置域名访问</a></li><ul class="second_class_ul"><li><a href="#_lab2_5_11">5.1 放行端口</a></li><li><a href="#_lab2_5_12">5.2 配置反向代理（推荐）</a></li></ul><li><a href="#_label6">六、常见错误及解决方案</a></li><ul class="second_class_ul"><li><a href="#_lab2_6_13">6.1next: command not found</a></li><li><a href="#_lab2_6_14">6.2Cannot find module 'xxx'</a></li><li><a href="#_lab2_6_15">6.3/usr/bin/env: 'node': No such file or directory</a></li><li><a href="#_lab2_6_16">6.4npm: command not found或pnpm: command not found</a></li><li><a href="#_lab2_6_17">6.5EACCES: permission denied</a></li><li><a href="#_lab2_6_18">6.6 构建时内存不足</a></li></ul><li><a href="#_label7">七、完整部署流程清单</a></li><ul class="second_class_ul"></ul><li><a href="#_label8">八、更新部署</a></li><ul class="second_class_ul"></ul><li><a href="#_label9">总结</a></li><ul class="second_class_ul"></ul></ul></div><p class="maodian"><a name="_label0"></a></p><h2>前言</h2><blockquote><p>本文记录在宝塔面板（Linux 服务器）上部署 Next.js 项目的完整流程，以及常见问题的解决方案。</p></blockquote>
<p class="maodian"><a name="_label1"></a></p><h2>一、环境准备</h2>
<p class="maodian"><a name="_lab2_1_0"></a></p><h3>1.1 安装 Node.js</h3>
<p>登录宝塔面板，进入 <strong>软件商店</strong>，搜索并安装 <strong>Node.js版本管理器</strong>。</p>
<p>安装完成后，选择一个 Node.js 版本（推荐 18.x 或 20.x 或 22.x）。</p>
<p class="maodian"><a name="_lab2_1_1"></a></p><h3>1.2 创建全局软链接（重要！）</h3>
<p>宝塔安装的 Node.js 默认不在系统 PATH 中，会导致各种 <code>command not found</code> 错误。</p>
<p><strong>查找 Node.js 安装路径：</strong></p>
<div class="jb51code"><pre class="brush:ps;">find /www -name "node" -type f 2>/dev/null
</pre></div>
<p>输出示例：<code>/www/server/nodejs/v22.20.0/bin/node</code></p>
<p><strong>创建软链接：</strong></p>
<div class="jb51code"><pre class="brush:ps;"># 根据上面查到的路径修改版本号
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
</pre></div>
<p class="maodian"><a name="_label2"></a></p><h2>二、上传项目代码</h2>
<p class="maodian"><a name="_lab2_2_2"></a></p><h3>2.1 正确的上传方式</h3>
<p><strong>✅ 正确做法：</strong> 只上传源代码文件，不上传 <code>node_modules</code></p>
<p>需要上传的文件：</p>
<ul><li><code>package.json</code></li><li><code>package-lock.json</code> 或 <code>pnpm-lock.yaml</code>（如果有）</li><li><code>src/</code> 或 <code>app/</code> 目录</li><li><code>public/</code> 目录</li><li>配置文件（<code>next.config.js</code>、<code>tailwind.config.js</code> 等）</li><li>其他源代码文件</li></ul>
<p><strong>❌ 错误做法：</strong> 直接复制本地的 <code>node_modules</code> 到服务器</p>
<p>原因：</p>
<ol><li><strong>平台差异</strong>：Windows 和 Linux 的二进制依赖不兼容</li><li><strong>符号链接失效</strong>：pnpm 使用硬链接/符号链接管理依赖，复制后会失效</li><li><strong>路径问题</strong>：某些包会记录绝对路径，复制后路径错误</li></ol>
<p class="maodian"><a name="_lab2_2_3"></a></p><h3>2.2 推荐的上传方式</h3>
<ul><li><strong>Git 拉取</strong>（推荐）：服务器上直接 <code>git clone</code> 或 <code>git pull</code></li><li><strong>宝塔文件管理</strong>：打包源代码为 zip，上传后解压</li><li><strong>SFTP/FTP</strong>：使用工具上传源代码文件</li></ul>
<p class="maodian"><a name="_label3"></a></p><h2>三、安装依赖并构建</h2>
<p class="maodian"><a name="_lab2_3_4"></a></p><h3>3.1 进入项目目录</h3>
<div class="jb51code"><pre class="brush:ps;">cd /www/wwwroot/你的项目目录
</pre></div>
<p class="maodian"><a name="_lab2_3_5"></a></p><h3>3.2 清理旧依赖（如果有）</h3>
<div class="jb51code"><pre class="brush:ps;">rm -rf node_modules
rm -f pnpm-lock.yaml package-lock.json yarn.lock
</pre></div>
<p class="maodian"><a name="_lab2_3_6"></a></p><h3>3.3 安装依赖</h3>
<p>使用 npm：</p>
<div class="jb51code"><pre class="brush:ps;">npm install
</pre></div>
<p>或使用 pnpm（更快）：</p>
<div class="jb51code"><pre class="brush:ps;">pnpm install
</pre></div>
<p class="maodian"><a name="_lab2_3_7"></a></p><h3>3.4 构建项目</h3>
<div class="jb51code"><pre class="brush:ps;">npm run build
# 或
pnpm build
</pre></div>
<p>构建成功后会生成 <code>.next</code> 目录。</p>
<p class="maodian"><a name="_label4"></a></p><h2>四、启动项目</h2>
<p class="maodian"><a name="_lab2_4_8"></a></p><h3>4.1 命令行启动（测试用）</h3>
<div class="jb51code"><pre class="brush:ps;">npm run start
# 或指定端口
npm run start -- -p 3004
</pre></div>
<p class="maodian"><a name="_lab2_4_9"></a></p><h3>4.2 使用 PM2 管理器启动（推荐）</h3>
<p>在宝塔面板安装 <strong>PM2管理器</strong>，然后添加项目：</p>
<table><thead><tr><th>配置项</th><th>值</th></tr></thead><tbody><tr><td>项目名称</td><td>自定义名称</td></tr><tr><td>项目目录</td><td><code>/www/wwwroot/你的项目目录</code></td></tr><tr><td>启动文件</td><td><code>npm</code></td></tr><tr><td>启动参数</td><td><code>run start</code> 或 <code>run start -- -p 3004</code></td></tr></tbody></table>
<p><strong>注意</strong>：添加项目前必须先手动完成 <code>npm install</code> 和 <code>npm run build</code></p>
<p class="maodian"><a name="_lab2_4_10"></a></p><h3>4.3 修改 package.json 指定端口（可选）</h3>
<div class="jb51code"><pre class="brush:json;">{
"scripts": {
"start": "next start -p 3004"
}
}
</pre></div>
<p class="maodian"><a name="_label5"></a></p><h2>五、配置域名访问</h2>
<p class="maodian"><a name="_lab2_5_11"></a></p><h3>5.1 放行端口</h3>
<p>在宝塔面板 <strong>安全 → 防火墙</strong> 中放行项目端口（如 3004）。</p>
<p>同时检查服务器厂商的安全组规则，确保端口已放行。</p>
<p class="maodian"><a name="_lab2_5_12"></a></p><h3>5.2 配置反向代理（推荐）</h3>
<p>如果想通过域名 + 80/443 端口访问，可以配置 Nginx 反向代理：</p>
<ol><li>在宝塔面板添加站点，绑定域名</li><li>进入站点设置 → <strong>反向代理</strong> → 添加反向代理</li><li>配置如下：</li></ol>
<table><thead><tr><th>配置项</th><th>值</th></tr></thead><tbody><tr><td>代理名称</td><td>自定义</td></tr><tr><td>目标URL</td><td><code>http://127.0.0.1:3004</code></td></tr><tr><td>发送域名</td><td><code>$host</code></td></tr></tbody></table>
<ol start="4"><li>可选：配置 SSL 证书启用 HTTPS</li></ol>
<p class="maodian"><a name="_label6"></a></p><h2>六、常见错误及解决方案</h2>
<p class="maodian"><a name="_lab2_6_13"></a></p><h3>6.1next: command not found</h3>
<p><strong>原因</strong>：依赖未安装或安装不完整</p>
<p><strong>解决</strong>：</p>
<div class="jb51code"><pre class="brush:ps;">rm -rf node_modules
npm install
</pre></div>
<p class="maodian"><a name="_lab2_6_14"></a></p><h3>6.2Cannot find module 'xxx'</h3>
<p><strong>原因</strong>：<code>node_modules</code> 不完整，通常是直接复制导致</p>
<p><strong>解决</strong>：</p>
<div class="jb51code"><pre class="brush:ps;">rm -rf node_modules
rm -f package-lock.json
npm install
</pre></div>
<p class="maodian"><a name="_lab2_6_15"></a></p><h3>6.3/usr/bin/env: 'node': No such file or directory</h3>
<p><strong>原因</strong>：Node.js 未添加到系统 PATH</p>
<p><strong>解决</strong>：创建软链接（见 1.2 节）</p>
<p class="maodian"><a name="_lab2_6_16"></a></p><h3>6.4npm: command not found或pnpm: command not found</h3>
<p><strong>原因</strong>：Node.js 未安装或未创建软链接</p>
<p><strong>解决</strong>：</p>
<ol><li>确认已在宝塔安装 Node.js 版本管理器</li><li>创建软链接（见 1.2 节）</li></ol>
<p class="maodian"><a name="_lab2_6_17"></a></p><h3>6.5EACCES: permission denied</h3>
<p><strong>原因</strong>：权限不足</p>
<p><strong>解决</strong>：</p>
<div class="jb51code"><pre class="brush:ps;">sudo npm install
# 或修改目录权限
chown -R www:www /www/wwwroot/你的项目目录
</pre></div>
<p class="maodian"><a name="_lab2_6_18"></a></p><h3>6.6 构建时内存不足</h3>
<p><strong>原因</strong>：服务器内存较小，Next.js 构建消耗内存较大</p>
<p><strong>解决</strong>：</p>
<div class="jb51code"><pre class="brush:ps;"># 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" npm run build
</pre></div>
<p>或在本地构建后上传 <code>.next</code> 目录（需要相同 Node.js 版本）。</p>
<p class="maodian"><a name="_label7"></a></p><h2>七、完整部署流程清单</h2>
<div class="jb51code"><pre class="brush:ps;"># 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 管理器中添加项目
</pre></div>
<p class="maodian"><a name="_label8"></a></p><h2>八、更新部署</h2>
<p>项目代码更新后，重新部署流程：</p>
<div class="jb51code"><pre class="brush:ps;">cd /www/wwwroot/你的项目目录
# 拉取最新代码（如果用 Git）
git pull
# 安装新依赖（如果 package.json 有变化）
npm install
# 重新构建
npm run build
# 重启项目（在 PM2 管理器中点击重启）
</pre></div>
<p class="maodian"><a name="_label9"></a></p><h2>总结</h2>
<table><thead><tr><th>步骤</th><th>命令/操作</th></tr></thead><tbody><tr><td>安装 Node.js</td><td>宝塔软件商店 → Node.js版本管理器</td></tr><tr><td>创建软链接</td><td><code>ln -sf /www/server/nodejs/vXX/bin/node /usr/bin/node</code></td></tr><tr><td>上传代码</td><td>只上传源代码，不上传 node_modules</td></tr><tr><td>安装依赖</td><td><code>npm install</code> 或 <code>pnpm install</code></td></tr><tr><td>构建项目</td><td><code>npm run build</code></td></tr><tr><td>启动项目</td><td>PM2 管理器 或 <code>npm run start</code></td></tr><tr><td>域名访问</td><td>配置 Nginx 反向代理</td></tr></tbody></table> 哇，写的太详细了！收藏了！
之前自己部署Next.js的时候踩了不少坑，尤其是那个软链接的问题，困扰了我好久。宝塔默认装的Node.js确实不在PATH里，每次敲命令都提示找不到，当时查了好久才解决。
补充几点个人经验：
1. 关于版本选择：个人建议用LTS版本，目前用20.x比较稳，22.x虽然新但有时候会有兼容性问题
2. 关于PM2：强烈建议用PM2管理，自动重启功能很实用，不然服务器重启后还要手动去启动
3. 关于构建：如果是小内存服务器（1G以下），建议本地build好直接上传.next目录，能省不少事
4. 关于反向代理：配置SSL的时候记得把"强制HTTPS"打开，不然会有一些奇怪的问题
总之这篇教程非常适合新手，照着操作基本不会出错。版主应该给加个精！
支持一下！
頁:
[1]