---
url: https://eoht.net/notes/vitepress/aapanel-deployment.md
description: >-
  在宝塔面板使用 Nginx 或 Apache 发布 VitePress 静态站点，核对 Node.js、项目脚本和输出目录，配置域名与
  HTTPS，并设置使用正确运行环境的定时构建任务。
---

# 宝塔面板部署 VitePress：静态目录、HTTPS 与定时构建 {#deploy-vitepress-with-aapanel}

VitePress 构建后生成 HTML、CSS 和 JavaScript，由 Nginx 或 Apache 直接提供访问。生产站点不需要常驻 `vitepress dev` 或 PM2；先确认构建成功，再把网站根目录指向构建输出。

## 1. 部署环境 {#prepare-deployment-environment}

* 使用仍受维护的服务器系统，并已安装宝塔面板和 Web 服务器。
* 准备域名、解析记录和已有 VitePress 项目；确认项目使用 npm、pnpm 还是其他包管理器。
* 按项目 `.nvmrc`、`package.json` 和锁文件选择 Node.js、包管理器版本，不直接照搬旧截图中的版本。

本文旧截图用于定位面板功能，菜单可能随版本变化。下文以项目目录 `/www/wwwroot/vitepress`、npm 和 `docs:build` 脚本为例，实际操作时按自己的项目替换。

## 2. 宝塔软件安装 {#install-aapanel-software}

### Nginx / Apache {#install-web-server}

安装其中一个即可，用来提供静态文件、绑定域名和配置 HTTPS。无需为 VitePress 开发服务器设置反向代理。

![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-222305%402x.webp "Nginx/Apache")

### Node.js 版本管理器 {#install-node-version-manager}

在面板中安装项目需要的 Node.js，并设置命令行使用的版本。Node.js 版本管理器与 PM2 管理器是不同功能。

![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-222617%402x.webp "Node.js 版本管理器")
![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-222723%402x.webp "选择项目要求的 Node.js 版本")
![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-222850%402x.webp "设置命令行 Node.js 版本")

用实际执行构建的账户打开终端，确认命令存在且版本一致：

```sh
command -v node
command -v npm
node --version
npm --version
```

## 3. 配置网站访问端口 {#open-port-8080}

### 服务器开放端口 {#open-server-firewall-port}

静态站点通常使用 HTTP 80 和 HTTPS 443。云服务器安全组与系统防火墙需同时允许所用端口；默认不必开放 8080。

* [阿里云安全组规则](https://help.aliyun.com/document_detail/25475.html)
* [腾讯云服务器安全组](https://cloud.tencent.com/document/product/213/39740)
* [腾讯云轻量应用服务器防火墙](https://cloud.tencent.com/document/product/1207/59924)

### 宝塔面板开放端口 {#open-aapanel-firewall-port}

检查面板“安全”中的规则是否与网站监听端口一致。面板管理端口与网站端口分开管理，测试页面时无需把开发或预览服务长期暴露到公网。

## 4. 建立网站及运行目录 {#create-site-and-root-directory}

在“网站”中添加域名，数据库选择“不创建”，站点类型选择纯静态。将域名解析到服务器，再按面板流程申请证书并配置 HTTPS。

![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-223335%402x.webp "添加静态站点")
![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-223817%402x.webp "网站与域名配置")
![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-224110%402x.webp "申请 SSL 证书")

源代码目录和公开的网站根目录需要区分。不要把含 `.git`、环境文件或源代码的整个项目作为公开目录；构建完成后再选择输出目录。无需为了静态站点统一关闭面板的目录保护功能，若访问被拒绝，应先核对站点路径、目录读取权限与 Web 服务器日志。

## 5. 命令行构建与发布 {#deploy-vitepress-from-terminal}

### 在项目目录安装依赖并构建 {#run-vitepress-setup-commands}

已有项目不需要重新执行 `vitepress init`。查看 `package.json` 中的脚本：如果脚本名是 `build`，下文的 `docs:build` 应替换为 `build`。

有 `package-lock.json` 的 npm 项目：

```sh
cd /www/wwwroot/vitepress
npm ci
npm run docs:build
```

有 `pnpm-lock.yaml` 的项目使用项目指定的 pnpm 版本：

```sh
cd /www/wwwroot/vitepress
pnpm install --frozen-lockfile
pnpm run docs:build
```

不要在同一个项目混用两套锁文件。全新项目应先按 [VitePress 入门文档](https://vitepress.dev/guide/getting-started) 初始化并保存依赖及锁文件，再部署到服务器。

| 构建命令 / 配置 | 默认输出目录 |
| --- | --- |
| `vitepress build`，根目录为项目本身 | `/www/wwwroot/vitepress/.vitepress/dist` |
| `vitepress build docs` | `/www/wwwroot/vitepress/docs/.vitepress/dist` |
| 配置了 `outDir` | 以配置解析出的实际目录为准 |

构建退出码为 0 后，检查输出目录含 `index.html` 和资源文件，再将宝塔网站根目录设置到该目录。

![宝塔面板 =688x](https://i.eoht.net/docs/WX20240223-224612%402x.webp "构建完成后设置网站目录")

发布后分别访问首页、文章直达链接和图片资源。启用 `cleanUrls` 的站点，还需要 Web 服务器把无扩展名路径映射到对应 `.html` 文件。Nginx 的相关 `location` 可参考以下形式，应用到现有站点配置时不要重复添加同路径块：

```nginx
location / {
  try_files $uri $uri.html $uri/ =404;
}
```

Apache 可按站点配置使用重写规则或 [MultiViews 内容协商](https://httpd.apache.org/docs/2.4/content-negotiation.html#multiviews)处理无扩展名路径。配置修改后先通过面板检查 Web 服务器配置，再重新加载；检查深层文章刷新是否正常，而不只看首页。相关要求见 [VitePress cleanUrls](https://vitepress.dev/reference/site-config#cleanurls)。

## 6. 定时构建静态文件 {#configure-automatic-builds}

在宝塔“计划任务”中新建 Shell 脚本。计划任务不会自动拉取仓库的新内容；应先明确源文件通过何种方式更新。代码或锁文件没有变化时，不必定时重复安装依赖。

计划任务的 `PATH` 可能与交互终端不同。先用上面的 `command -v` 找到 Node.js 和 npm 所在目录，将其加入任务的 `PATH`，并确认任务账户有项目和输出目录的读写权限。不要把示例中的占位目录直接用于任务。

```sh
#!/bin/sh
set -eu
# 替换为当前项目 Node.js / npm 的实际可执行文件目录
export PATH="/path/to/node/bin:/usr/local/bin:/usr/bin:/bin"
cd /www/wwwroot/vitepress
node --version
npm --version
npm run docs:build
test -f .vitepress/dist/index.html
```

如果文档根目录是 `docs`，最后一行改为检查 `docs/.vitepress/dist/index.html`；pnpm 项目则换成对应 pnpm 构建命令。先手动运行任务并查看日志，再设置执行周期，避免任务重叠。

直接在公开输出目录重建期间可能出现文件暂缺。需要连续可用的站点，应在独立目录完成构建与检查后切换发布目录，并保留上一版用于回退。发布方式、缓存刷新和备份策略由自己的服务器配置决定。

参考：[VitePress 部署文档](https://vitepress.dev/guide/deploy)。