宝塔面板部署 VitePress：静态目录、HTTPS 与定时构建

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

1. 部署环境

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

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

2. 宝塔软件安装

Nginx / Apache

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

Node.js 版本管理器

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

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

command -v node
command -v npm
node --version
npm --version

3. 配置网站访问端口

服务器开放端口

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

宝塔面板开放端口

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

4. 建立网站及运行目录

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

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

5. 命令行构建与发布

在项目目录安装依赖并构建

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

有 package-lock.json 的 npm 项目：

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

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

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

不要在同一个项目混用两套锁文件。全新项目应先按 VitePress 入门文档初始化并保存依赖及锁文件，再部署到服务器。

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

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

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

nginx

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

Apache 可按站点配置使用重写规则或 MultiViews 内容协商处理无扩展名路径。配置修改后先通过面板检查 Web 服务器配置，再重新加载；检查深层文章刷新是否正常，而不只看首页。相关要求见 VitePress cleanUrls。

6. 定时构建静态文件

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

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

#!/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 部署文档。

宝塔面板部署 VitePress：静态目录、HTTPS 与定时构建 ​

1. 部署环境 ​

2. 宝塔软件安装 ​

Nginx / Apache ​

Node.js 版本管理器 ​

3. 配置网站访问端口 ​

服务器开放端口 ​

宝塔面板开放端口 ​

4. 建立网站及运行目录 ​

5. 命令行构建与发布 ​

在项目目录安装依赖并构建 ​

6. 定时构建静态文件 ​