个人博客部署到云服务器后,发布一篇文章需要完成两件事:把 Markdown 文件上传到服务器,再重新构建 Astro 静态站点。
手动执行时,完整流程大致如下:
选择文章 → SCP 上传 → SSH 登录 → pnpm build → 检查 Nginx → 打开网站验证步骤并不复杂,但每次重复输入路径和命令很容易出错。更重要的是,Astro 构建会更新整个 dist 目录,如果构建中途失败,线上站点可能只剩下一份不完整的产物。
为了解决这些问题,我给博客增加了两个脚本:
- Windows PowerShell 上传脚本:选择 Markdown、判断目标目录、执行 SCP,并远程触发构建;
- Linux 服务器更新脚本:加锁、备份旧版本、执行构建、失败回滚、检查 Nginx 和线上地址。
现在,发布一篇博客只需要一条本地命令。
当前目录结构
我把正在编辑的 Markdown 集中保存在:
X:\path\to\blog-content其中包含普通文章和 About 页面:
X:\path\to\blog-content\├─ about.md├─ first-post.md└─ deployment-notes.md服务器上的 Astro 项目位于:
/var/www/example-blog两个内容目录分别是:
/var/www/example-blog/src/content/posts # 普通文章/var/www/example-blog/src/content/spec # About 等特殊页面脚本会根据文件内容和文件名自动选择目录。about.md 会进入 spec,带有 Astro Frontmatter 的其他 Markdown 会进入 posts。
准备 SSH 别名
本地 SSH 配置文件位于:
C:\Users\<USERNAME>\.ssh\config对应配置如下:
Host blog-server HostName 203.0.113.10 User deploy IdentityFile C:\Users\<USERNAME>\.ssh\id_ed25519 IdentitiesOnly yes配置后,不再需要每次输入 IP、用户名和密钥路径:
ssh blog-server测试成功后,SCP 也可以使用相同别名:
scp .\example.md blog-server:/tmp/私钥只保存在本机,不能上传到博客目录或 GitHub。服务器的 authorized_keys 中只需要保存公钥。
安装服务器更新脚本
服务器脚本的本地位置是:
X:\path\to\blog-project\scripts\update-blog.sh先在 Windows PowerShell 中上传:
scp -F "$env:USERPROFILE\.ssh\config" ` "X:\path\to\blog-project\scripts\update-blog.sh" ` blog-server:/tmp/update-blog.sh然后登录服务器:
ssh -F "$env:USERPROFILE\.ssh\config" blog-server将脚本安装为系统命令:
install -o root -g root -m 755 \ /tmp/update-blog.sh \ /usr/local/bin/update-blog检查是否安装成功:
update-blog --help以后即使使用 MobaXterm 手动上传文件,也只需要在服务器执行:
update-blog服务器脚本做了什么
服务器脚本首先固定项目地址和正式域名:
BLOG_DIR="${BLOG_DIR:-/var/www/example-blog}"SITE_URL="${SITE_URL:-https://blog.example.com/}"BACKUP_DIR="${BLOG_BACKUP_DIR:-/var/backups/example-blog}"KEEP_BACKUPS="${KEEP_BACKUPS:-5}"这些值都可以通过环境变量覆盖,但平时不需要修改。
防止重复构建
如果不小心连续运行两次更新,两个 pnpm 进程可能同时修改 dist。脚本使用 flock 创建部署锁:
exec 9>"/var/lock/example-blog-update.lock"flock -n 9 || { echo "已有更新任务正在运行" exit 1}只要已有任务没有退出,第二个任务就不会继续执行。
构建前备份
如果当前站点已经存在,脚本会把 dist 打包:
timestamp="$(date '+%Y%m%d-%H%M%S')"backup_file="/var/backups/example-blog/dist-$timestamp.tar.gz"
tar -czf "$backup_file" \ -C /var/www/example-blog/dist .默认只保留最近五份备份,防止长期更新占满磁盘。
使用正式域名构建
博客通过 SITE_URL 生成规范链接、RSS 和 Sitemap,因此每次构建都显式传入正式域名:
cd /var/www/example-blogSITE_URL="https://blog.example.com/" pnpm run build随后检查首页构建产物:
test -f /var/www/example-blog/dist/index.html只有 dist/index.html 存在,构建才会被视为成功。
失败自动回滚
脚本通过 trap 捕获构建错误和中断信号。如果 Astro 构建失败,会删除残缺的 dist,再从刚才的备份恢复:
rm -rf /var/www/example-blog/distmkdir -p /var/www/example-blog/disttar -xzf "$backup_file" \ -C /var/www/example-blog/dist这样,即使新文章的 Frontmatter 写错,线上站点仍然保持为上一次成功构建的版本。
检查服务状态
构建成功后,脚本检查并重新加载 Nginx:
nginx -tsystemctl reload nginx最后访问正式地址进行健康检查:
curl --fail --location --head \ --max-time 20 \ https://blog.example.com/如果网站暂时无法访问,脚本会打印警告,但不会把一次成功构建误判成构建失败。
使用本地上传脚本
本地 PowerShell 脚本位于:
X:\path\to\blog-project\scripts\upload-blog.ps1它默认从下面的目录寻找 Markdown:
X:\path\to\blog-content因此发布文章时只需要提供文件名。
上传单篇文章
powershell -ExecutionPolicy Bypass -File ` "X:\path\to\blog-project\scripts\upload-blog.ps1" ` "new-article.md"上传这篇教程本身则执行:
powershell -ExecutionPolicy Bypass -File ` "X:\path\to\blog-project\scripts\upload-blog.ps1" ` "upload-astro-blog-with-ssh-script.md"脚本会依次显示上传、服务器构建和网站检查结果。
批量同步全部文章
powershell -ExecutionPolicy Bypass -File ` "X:\path\to\blog-project\scripts\upload-blog.ps1" ` -All批量模式会扫描 X:\path\to\blog-content 下的所有 .md 文件,并进行分类:
about.md自动上传到src/content/spec;- 包含
title、published和完整 Frontmatter 的文件上传到src/content/posts; - 普通命令备忘录或缺少 Frontmatter 的 Markdown 会被跳过。
这项检查可以避免把一个普通笔记误当成 Astro 文章,导致服务器构建失败。
依赖发生变化时
平时上传 Markdown 不需要重新安装依赖。如果同时修改了 package.json 或 pnpm-lock.yaml,可以增加参数:
powershell -ExecutionPolicy Bypass -File ` "X:\path\to\blog-project\scripts\upload-blog.ps1" ` "example.md" ` -InstallDeps服务器会在构建前执行:
pnpm install --frozen-lockfile新文章的最小格式
上传脚本会检查普通文章是否包含 Astro Frontmatter。一个最小的博客文件如下:
---title: "文章标题"published: 2026-09-20description: "文章简介"tags: [Astro, 教程]category: 开发记录draft: falselang: zh_CN---
这里开始写正文。将文件保存到:
X:\path\to\blog-content\example.md随后运行:
powershell -ExecutionPolicy Bypass -File ` "X:\path\to\blog-project\scripts\upload-blog.ps1" ` "example.md"常见问题
PowerShell 禁止运行脚本
如果出现“系统上禁止运行脚本”,使用本文命令中的:
-ExecutionPolicy Bypass它只对本次 PowerShell 进程生效,不会永久修改系统执行策略。
提示找不到文件
脚本默认只在 X:\path\to\blog-content 中寻找相对文件名。先确认文件确实存在:
Get-ChildItem "X:\path\to\blog-content\*.md"也可以直接传入完整路径。
文件被跳过
普通文章必须:
- 以
---开始; - 包含
title:; - 包含
published:; - 使用第二个
---结束 Frontmatter。
about.md 是特殊页面,不需要这些字段。
服务器提示 pnpm 不存在
在服务器执行:
corepack enablecorepack prepare pnpm@9.14.4 --activatepnpm --version版本应与项目 package.json 中声明的版本一致。
构建失败
服务器脚本会显示 Astro 或 Pagefind 的原始错误,并自动恢复上一个 dist。修正文档后重新上传即可。
可以查看最近的备份:
ls -lht /var/backups/example-blog上传成功但看不到新文章
依次检查:
ls -l /var/www/example-blog/src/content/postsls -l /var/www/example-blog/dist/index.htmlcurl -I https://blog.example.com/浏览器仍显示旧内容时,可以尝试强制刷新页面,或者清除浏览器缓存。
这套流程带来的变化
最初更新博客需要记住服务器目录、构建命令和正式域名。现在,本地脚本负责“把内容送到哪里”,服务器脚本负责“怎样安全地发布”。两边的职责很清楚:
本地 Markdown ↓ SCP服务器源码目录 ↓ 自动备份与构建Astro dist ↓ Nginxhttps://blog.example.com/自动化的价值不只是少输入几条命令。部署锁避免重复构建,Frontmatter 检查减少无效上传,备份和回滚保护线上版本,健康检查则让每次发布都有明确结果。
对于个人博客,这套方案已经足够轻量:不依赖额外的持续集成平台,也不要求每篇文章先提交到 GitHub。写完 Markdown,运行一条命令,剩下的工作交给脚本完成。