VuePress 2 博客搭建与部署(现行方案)
VuePress 2 博客搭建与部署(现行方案)
本文描述的是当前实际在用的方案:VuePress 2 + vuepress-theme-hope 构建静态站,部署到阿里云 ECS 的 nginx,HTTPS 由 Let's Encrypt 自动续期。
若你只是想改内容、发新文章,直接跳到 第 6 节 一键发布。
最后更新:2026-11-20
1. 线上环境一览
| 项目 | 值 |
|---|---|
| 站点地址 | https://www.ouyangss.site、https://ouyangss.site |
| 服务器公网 IP | 39.97.254.3 |
| 系统 | Debian GNU/Linux 12 (bookworm),系统盘 40G |
| 内网访问 | WireGuard,服务端 10.0.0.1,本机 10.0.0.2 |
| Web 服务器 | nginx 1.22.1 |
| 站点根目录 | /var/www/my-docs/dist(软链接 → releases/<时间戳>) |
| nginx 站点配置 | /etc/nginx/sites-available/my-docs |
| 证书目录 | /etc/letsencrypt/live/ouyangss.site/ |
| 签发方式 | Let's Encrypt + certbot(90 天,自动续期) |
| ICP 备案 | 鄂ICP备2026044211号-1 |
2. 本地环境
- Node.js v18 以上(当前 v22.19.0)
- npm 10.x
- WireGuard Windows 客户端(发布时需要通过隧道或公网 SSH 到服务器)
- 建议用 VS Code 编辑,保存为 UTF-8 编码
node -v # v22.19.0
npm -v # 10.9.33. 项目结构
my-docs/
├── package.json # docs:dev / docs:build 脚本
├── deploy.ps1 # 一键发布脚本(构建→上传→原子切换→校验)
└── docs/
├── README.md # 首页
├── about.md
├── java/ # Java 笔记
├── python/ # Python 笔记
├── C/ # C/C++ 笔记
├── WebsiteSetup/ # 本站技术细节(含本文)
└── .vuepress/
├── config.js # 站点配置、导航、侧边栏
├── client.js # 备案信息页脚等客户端组件
├── public/ # 静态资源(avatar.jpg 等)
└── dist/ # 构建产物(不提交,发布时上传)依赖说明(devDependencies):
{
"vuepress": "^2.0.0-rc.30",
"vuepress-theme-hope": "^2.0.0-rc.107",
"@vuepress/bundler-vite": "^2.0.0-rc.30",
"sass-embedded": "^1.100.0"
}4. 本地开发
npm install # 首次或依赖变更后
npm run docs:dev # 默认 http://localhost:8080热更新,改 Markdown 即时生效。端口被占用时可以指定:
npx vuepress dev docs --port 80815. 构建
npm run docs:build产物在 docs/.vuepress/dist/,通常 40 余个文件、约 0.25 MB(压缩后)。构建耗时约 2 秒。
构建会顺带生成 robots.txt、sitemap.xml 以及各类路由页面。
6. 一键发布:deploy.ps1
6.1 用法
.\deploy.ps1 # 构建 + 上传 + 原子切换 + 线上校验
.\deploy.ps1 -SkipBuild # 跳过构建,直接上传现有 dist脚本文件:项目根目录 deploy.ps1。
6.2 它做了什么
| 步骤 | 动作 |
|---|---|
| 1 | npm run docs:build 构建(可 -SkipBuild 跳过) |
| 2 | 把 dist/ 打成 my-docs-dist.tar.gz |
| 3 | scp 上传到服务器 /tmp/ |
| 4 | 解压到 /var/www/my-docs/releases/<时间戳>,软链接 dist 原子切换 |
| 5 | curl 线上首页,非 200 直接报错退出 |
6.3 发布模型:为什么用 releases + 软链接
/var/www/my-docs/
├── releases/
│ ├── 20261120-003754/
│ └── 20261120-003838/ ← 当前生效(最新)
└── dist -> releases/20261120-003838好处:
- 原子切换:
ln -sfn+mv -Tf是一次性的,不会出现"删了旧文件、新文件还没到"的空窗期 - 可回滚:旧版本还在,一条命令切回去
- 不删站点目录:脚本里没有任何
rm -rf指向站点路径(这条规矩是有事故教训的,见 部署事故复盘) - 脚本只保留最近 5 个版本,自动清理更早的
6.4 注意事项
- 必须通过 SSH 能到服务器:默认目标是 WireGuard 的
root@10.0.0.1;走公网就改参数.\deploy.ps1 -Server root@39.97.254.3 - 文件必须是 UTF-8 with BOM:Windows PowerShell 5.1 会把无 BOM 的 UTF-8 当 GBK 读,中文注释里的引号会破坏语法解析。
deploy.ps1已带 BOM,用编辑器改完记得保持。 - 脚本对
-RemoteBase做了格式白名单校验(必须形如/var/www/<名称>),防止路径变量异常导致误删。
6.5 手动发布(脚本不可用时)
# 本地:打包
tar -czf dist.tar.gz -C docs/.vuepress/dist .
# 上传
scp dist.tar.gz root@39.97.254.3:/tmp/
# 服务器:解压到新版本目录并切换
TS=$(date +%Y%m%d-%H%M%S)
mkdir -p /var/www/my-docs/releases/$TS
tar -xzf /tmp/dist.tar.gz -C /var/www/my-docs/releases/$TS
ln -sfn /var/www/my-docs/releases/$TS /var/www/my-docs/dist.new
mv -Tf /var/www/my-docs/dist.new /var/www/my-docs/dist不要用
rm -rf /var/www/my-docs/dist/*这类写法清空目录,原因见事故复盘。
7. nginx 配置
站点配置 /etc/nginx/sites-available/my-docs(sites-enabled 里是软链接):
# my-docs (VuePress) - static site
# root is a symlink to /var/www/my-docs/releases/<timestamp>
server {
listen 443 ssl;
listen [::]:443 ssl ipv6only=on;
server_name ouyangss.site www.ouyangss.site;
root /var/www/my-docs/dist;
index index.html;
charset utf-8;
ssl_certificate /etc/letsencrypt/live/ouyangss.site/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/ouyangss.site/privkey.pem; # managed by Certbot
include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
# 目录式路由 + 前端路由回退
location / {
try_files $uri $uri/ $uri.html /index.html;
}
# 带哈希的构建产物长缓存
location /assets/ {
expires 30d;
add_header Cache-Control "public, immutable";
try_files $uri =404;
}
location = /favicon.ico {
access_log off;
log_not_found off;
}
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_comp_level 5;
gzip_types text/plain text/css application/javascript application/json image/svg+xml application/xml;
}
# 全站 HTTP 跳转到 HTTPS
server {
listen 80;
listen [::]:80;
server_name ouyangss.site www.ouyangss.site;
return 301 https://$host$request_uri; # managed by Certbot
}要点:
try_files $uri $uri/ $uri.html /index.html:VuePress 页面是xxx.html形式,刷新子页面不能 404root指向软链接,nginx 会跟随,所以发布切换后不需要重载 nginx# managed by Certbot注释要保留,certbot 靠它们定位并更新证书路径
改完配置务必校验再重载:
sudo nginx -t
sudo systemctl reload nginx8. HTTPS:Let's Encrypt 自动续期
早期的阿里云免费证书只有 3 个月且要手动重新申请,现已改为 Let's Encrypt + certbot(90 天,到期前自动续)。
8.1 安装
sudo apt update
sudo apt install -y certbot python3-certbot-nginx8.2 关键前置:优先 IPv4
服务器只有 IPv4 出口,但 acme-v02.api.letsencrypt.org 默认会先解析到 IPv6,导致每个 ACME 请求都干等超时(报 Read timed out)。修法:
echo 'precedence ::ffff:0:0/96 100' | sudo tee -a /etc/gai.conf验证:
getent ahosts acme-v02.api.letsencrypt.org | head -3 # 应显示 IPv48.3 签发
sudo certbot --nginx -d ouyangss.site -d www.ouyangss.site \
--non-interactive --agree-tos --register-unsafely-without-email --redirect--nginx 会让 certbot 自动改写站点配置(加 443、证书路径、80 跳转),无需手写。
证书文件位置:
/etc/letsencrypt/live/ouyangss.site/fullchain.pem # 证书链
/etc/letsencrypt/live/ouyangss.site/privkey.pem # 私钥8.4 续期
systemctl list-timers certbot.timer # 查看下次续期时间
sudo certbot renew --dry-run # 演练,不真正签发
sudo certbot certificates # 查看证书与到期时间certbot.timer 每天跑两次,到期前 30 天内自动续并重载 nginx。国际线路较慢时单次可能耗十几分钟,属正常现象,不要中途 Ctrl+C。
8.5 换域名 / 加域名
sudo certbot --nginx -d 新域名 -d www.新域名 --expand --redirect9. 域名解析与备案
DNS(阿里云云解析)需要两条 A 记录指向 39.97.254.3:
| 记录类型 | 主机记录 | 记录值 |
|---|---|---|
| A | @ | 39.97.254.3 |
| A | www | 39.97.254.3 |
- 中国大陆服务器必须 ICP 备案,本站备案号
鄂ICP备2026044211号-1,展示在页脚(见docs/.vuepress/client.js) - 安全组需放行 TCP 80、TCP 443;WireGuard 另需 UDP 51820
10. 日常运维
# 当前生效版本
readlink -f /var/www/my-docs/dist
# 历史版本
ls -1 /var/www/my-docs/releases/
# 回滚到上一个版本(把 20261120-003754 换成目标版本)
ln -sfn /var/www/my-docs/releases/20261120-003754 /var/www/my-docs/dist.new
mv -Tf /var/www/my-docs/dist.new /var/www/my-docs/dist
# 服务状态
systemctl status nginx --no-pager
systemctl status certbot.timer --no-pager磁盘占用很小(站点 0.25 MB + 5 个版本),无需特别清理。
11. 常见问题
| 现象 | 原因与处理 |
|---|---|
| 部署后 404 | 检查 root 是否指向 /var/www/my-docs/dist,try_files 是否含 $uri.html /index.html |
| 刷新子页面 404 | 同上,前端路由回退缺失 |
certbot 报 Read timed out | IPv6 优先导致,按 8.2 配置 gai.conf |
证书签发报 Could not bind TCP port 80 | 80 被其他服务占用,或安全组未放行 |
npm run docs:dev 报 stream did not contain valid UTF-8 | config.js 不是 UTF-8,另存为 UTF-8 |
| PowerShell 脚本报引号/中文解析错误 | 文件缺少 UTF-8 BOM(PS 5.1 按 GBK 读) |
| 页面样式缺失 | sass-embedded 未安装,npm i -D sass-embedded |
| 发布后仍是旧内容 | 浏览器缓存;/assets/ 是长缓存,但文件名带哈希会自动更新,强刷即可 |
鄂公网安备42011102006488号