# 宝塔面板 Next.js 项目部署教程

> 使用宝塔面板（BT Panel）部署 Next.js 项目的完整教程，通过 Node.js 项目管理与 PM2 实现生产环境部署，含依赖安装、构建、守护进程与反向代理站点配置。

# Next.js 项目部署教程

本教程介绍如何使用宝塔面板部署 Next.js 项目，通过 PM2 守护进程确保应用持续运行。

## 准备环境

### 所需环境

| 环境组件 | 版本要求 |
| --- | --- |
| **宝塔面板** | 11.0+ |
| **Node.js 版本管理器** | 2.7+ |
| **Node.js** | v14.17.6+（推荐 v18 LTS） |
| **Nginx** | 1.20+ |
| **MySQL**（如需数据库）| 5.7+ / 8.0+ |

### 安装必要组件

1. **安装 Node.js 版本管理器**
   - 进入 **软件商店** → 搜索 **Node 版本管理器**
   - 点击 **安装**

2. **安装 Node.js**
   - 打开 Node 版本管理器
   - 选择需要的 Node.js 版本（如 v14.17.6 或 v18）
   - 点击 **安装**

![环境准备](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/env-setup.png)

3. **设置命令行版本**
   - 进入 **网站** → **Node 项目**
   - 设置命令行使用的 Node.js 版本

![Node 版本选择](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/node-version-select.png)

## 上传项目文件

### 1. 上传项目压缩包

1. 打开 **文件** → 进入 `/www/wwwroot/` 目录
2. 点击 **上传** 按钮，选择项目压缩包

![上传项目](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/upload-project.png)

### 2. 解压项目

上传完成后，右键点击压缩包，选择 **解压**。

![解压项目](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/extract-project.png)

## 配置数据库（如需要）

如果您的 Next.js 项目需要连接数据库，请按以下步骤配置。

### 1. 创建数据库

1. 进入 **数据库** → **MySQL**
2. 点击 **添加数据库**
3. 输入数据库名称（如 `node_ce`）
4. 设置用户名和密码

![创建数据库](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/create-database.png)

### 2. 导入 SQL 文件

如果项目包含初始化 SQL 文件（如 `database_setup.sql`）：

1. 在数据库列表中找到刚创建的数据库
2. 点击 **导入**
3. 选择 SQL 文件上传并导入

![导入 SQL](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/import-sql.png)

### 3. 修改数据库连接配置

编辑项目中的数据库配置文件（如 `lib/db.ts`、`config/database.js` 等）：

```typescript
// 示例：lib/db.ts
export const dbConfig = {
  host: 'localhost',
  user: 'node_ce',        // 您的数据库用户名
  password: 'your_password', // 您的数据库密码
  database: 'node_ce',    // 您的数据库名
  port: 3306
};
```

![数据库配置](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/db-config.png)

:::warning 远程连接配置
如果使用 root 用户连接数据库，需要确保 MySQL 允许远程连接。可以在 **数据库** → **MySQL 设置** 中配置。
:::

## 构建项目

在部署前，需要先构建 Next.js 项目。

### 在终端中构建

1. 进入 **终端**（或使用 SSH）
2. 切换到项目目录：
   ```bash
   cd /www/wwwroot/your-project-name
   ```

3. 安装依赖：
   ```bash
   npm install
   # 或使用 yarn
   yarn install
   ```

4. 构建项目：
   ```bash
   npm run build
   # 或使用 yarn
   yarn build
   ```

![构建项目](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/build-project.png)

:::tip 提示
构建过程可能需要几分钟时间，请耐心等待。
:::

## 部署 Node 项目

### 1. 创建 Node 项目

1. 进入 **网站** → **Node 项目**
2. 点击 **添加 Node 项目**

![部署 Node 项目](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/deploy-node-project.png)

### 2. 配置项目信息

填写以下配置：

| 配置项 | 说明 | 示例 |
| --- | --- | --- |
| **项目名称** | 自定义项目名称 | `my-nextjs-app` |
| **项目路径** | 项目所在目录 | `/www/wwwroot/your-project-name` |
| **启动文件** | Next.js 启动文件 | `node_modules/next/dist/bin/next` |
| **启动命令** | 启动参数 | `start -p 3000` |
| **端口** | 应用运行端口 | `3000` |
| **Node 版本** | 选择已安装的版本 | `v14.17.6` 或 `v18` |

![端口配置](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/port-config.png)

:::info 关于 PM2
宝塔面板的 Node 项目管理默认使用 PM2 作为守护进程，确保应用自动重启和持续运行。
:::

### 3. 启动项目

配置完成后，点击 **提交**，系统会自动启动项目。

## 测试访问

### 通过端口访问

在浏览器中访问：`http://您的服务器IP:3000`

![测试访问](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/test-access.png)

如果页面正常显示，说明部署成功！

## 配置 80 端口访问

为了让用户通过域名或 IP 直接访问（不带端口号），需要配置外网映射。

### 1. 开启外网映射

1. 在 Node 项目列表中，点击项目的 **设置**
2. 找到 **外网映射** 选项
3. 点击 **开启**

![外网映射设置](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/external-mapping.png)

### 2. 配置映射规则

- **域名**：填入您的域名（可选）
- **外网端口**：填写 `80`（HTTP）或 `443`（HTTPS）
- **内网端口**：填写应用运行端口 `3000`

![启用映射](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/enable-mapping.png)

### 3. 测试访问

现在可以直接通过域名或 IP 访问网站：`http://您的域名` 或 `http://您的IP`

![最终测试](https://docs.bt.cn/img/practical-tutorials/nextjs-deployment/final-test.png)

## 相关资源

- [Next.js 官方文档](https://nextjs.org/docs)
- [PM2 官方文档](https://pm2.keymetrics.io/docs/usage/quick-start/)
- [宝塔 Node 项目管理](https://www.bt.cn)