VitePress 服务器部署与 Git 同步踩坑记录
好的，我帮你整理一篇文章草稿，总结你在 VitePress 服务器部署 + Git 同步 + 构建 过程中踩过的坑，以及 Git 操作经验。文章内容分条清晰，方便你存档和以后查阅。
VitePress 服务器部署与 Git 同步踩坑记录
1. 环境与版本
- 服务器系统：Ubuntu / Debian
- Node.js：v24.11.0（注意不要用低版本，VitePress 2.x 需要 >=18）
- Yarn：1.22.x
- VitePress：v1.6.x 或 v2.x
注意：低版本 Node 安装 VitePress 会报错：
globby@14.1.0: The engine "node" is incompatible with this module. Expected version ">=18". Got "14.17.6"2. 服务器部署流程
- 创建项目目录：
mkdir/www/wwwroot/vitepresscd/www/wwwroot/vitepress
- 初始化 Node 项目并安装 VitePress：
yarninit-yyarnadd-Dvitepress
- 创建必要文件：
index.mdmarkdown-examples.mdapi-examples.md.vitepress/config.mts
- 配置 Nginx 指向
.vitepress/dist目录，使用location /访问 VitePress 站点。 - 构建 VitePress：
yarnvitepress build
坑：
- 之前使用 VuePress 命令构建，报错
The bundler or theme option is missing，解决方法：确认使用 VitePress 而不是 VuePress。 - 构建时
.user.ini文件权限问题会报EPERM，解决方法：确保构建目录可写，或清理旧文件：
rm-rf.vitepress/dist/*
3. 本地同步与服务器操作
使用 rsync 同步
本地修改后，可以通过 rsync 同步到服务器：
rsync-avz--exclude'node_modules'--exclude'.vitepress/dist'./ user@server:/www/wwwroot/vitepress/
排除目录：
node_modules/.vitepress/dist/（构建产物，无需同步）- 可按需排除
.cache或日志文件
构建流程
在服务器上：
cd/www/wwwroot/vitepressyarnvitepress build
生成静态文件在 .vitepress/dist/，Nginx 指向此目录即可访问。