Astro 博客从零构建到 VPS 自动化部署指南

这篇笔记记录了如何搭建一个高性能的 Astro 静态博客，并实现“写完 Markdown 推送 GitHub，服务器自动更新”的 CI/CD 流程。

---

第一阶段：本地构建 Astro 项目

1. 初始化项目

官方安装指南

确保本地 Node.js 版本 > v18.14.1。

# 1. 创建项目 (推荐使用官方博客模板，省去很多配置)
npm create astro@latest my-blog
# > 选项选择：
# > template: Blog
# > install dependencies: Yes
# > git: Yes

# 2. 进入目录
cd my-blog

# 3. 启动开发服务器查看效果
npm run dev

2. 配置 Content Collections (Markdown 规范)

Astro 的核心优势是类型安全的 Markdown。打开 src/content/config.ts，确保 Schema 定义符合你的需求：

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
    type: 'content',
    schema: ({ image }) => z.object({
        title: z.string(),
        description: z.string(),
        // 自动转换字符串日期为 Date 对象
        pubDate: z.coerce.date(),
        updatedDate: z.coerce.date().optional(),
        // 图片验证，确保路径正确
        heroImage: image().optional(),
    }),
});

export const collections = { blog };

3. 撰写与管理文章

• 图片存放： 建议放在 src/assets/ 下，或者使用“文件夹式文章”结构。
• Frontmatter 补全： 根据Schema配置一个 VS Code Snippet (fm + Tab) 快速生成头部信息。
• 批量处理： 如果有大量旧文章，编写并运行脚本 node update-frontmatter.cjs 进行标准化。

---

第二阶段：VPS 服务器准备 (接收端)

假设你有一台安装了 Ubuntu/Debian 的 VPS。

1. 安装 Nginx

我们需要 Nginx 来作为 Web 服务器托管静态文件。

# SSH 登录 VPS
ssh root@your_server_ip

# 更新软件源并安装 Nginx（如果已经安装并启用，忽略）
apt update
apt install nginx -y

# 启动 Nginx
systemctl start nginx
systemctl enable nginx

2. 创建网站目录

这是 GitHub Actions 最终要把文件传送到的地方。

# 创建目录 (假设项目名叫 my-blog)
mkdir -p /var/www/my-blog/dist

# 修改权限 (确保当前用户有权写入，这里假设使用 root 或 ubuntu 用户)
# 如果是 ubuntu 用户: sudo chown -R ubuntu:ubuntu /var/www/my-blog

3. 配置 Nginx

新建配置文件：/etc/nginx/sites-available/my-blog

server {
    listen 80;
    server_name your_domain.com; # 换成你的域名或 IP

    root /var/www/my-blog/dist;  # 指向 Astro 构建后的 dist 目录
    index index.html;

    # 此location并非转发端口
    location / {
        try_files $uri $uri/ /index.html; # 支持 SPA 路由（如果有）或 404 页
    }

    # 可选：开启 gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

启用配置并重启：

ln -s /etc/nginx/sites-available/my-blog /etc/nginx/sites-enabled/

nginx -t # 测试配置是否正确

systemctl reload nginx # 重启

4.再次运行 Certbot SSL 配置

首次配置ssl参考：拿到一台新VPS该做的事

我们要让 Certbot 重新扫描一次，把 SSL 配置“注入”进去。

输入：

sudo certbot --nginx

接下来会出现的情况：

它会检测到你在配置文件里写的域名，问你是不是要给这几个域名配置 HTTPS。输入对应的数字（例如 1 或 1,2），回车。

关键点： 因为你之前申请过证书，它可能会提示你：

You have an existing certificate that has exactly the same domains... (1) Attempt to reinstall this existing certificate （尝试重新安装现有证书） (2) Renew & replace the cert （重新申请并替换）

请选择 1 (Reinstall)。因为证书还在硬盘里，我们要做的只是把配置找回来，不需要重新向官方申请。

接着它可能会问你是否要开启 Redirect (强制跳转)：

(1) No redirect (2) Redirect

建议选择 2。这样以后用户访问 http:// 会自动跳到 https://，更安全。

Certbot 跑完后，它会自动修改你的 Nginx 配置并重启服务。

---

第三阶段：配置 GitHub Actions (自动化桥梁)

这一步实现了：只要你 push 代码到 main 分支，GitHub 就会自动打包并把文件传到 VPS。

1. 在你的【本地电脑】（不是 VPS）重新生成一对钥匙：

名字取个好记的，比如 astro_deploy

ssh-keygen -t rsa -b 4096 -f ~/.ssh/astro_deploy

一路回车，不要设密码

2. 获取公钥内容（这是要给 VPS 的）：

cat ~/.ssh/astro_deploy.pub

复制输出的所有内容（以 ssh-rsa 开头）

3. 在【VPS】上把这把锁加上去：

1. 确保 .ssh 目录存在

mkdir -p ~/.ssh

2. 编辑 authorized_keys 文件

nano ~/.ssh/authorized_keys

在打开的编辑器里，移动到最后一行，粘贴刚才复制的公钥内容。

按 Ctrl + O -> Enter 保存。

按 Ctrl + X 退出。

4. 设置权限（VPS 上）：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

5. 获取私钥内容（这是要给 GitHub 的）：

回到【本地电脑】：

cat ~/.ssh/astro_deploy
# 复制全部内容（包括 BEGIN 和 END 那两行）

6. 配置 GitHub Secrets

进入你的 GitHub 仓库页面 -> Settings -> Secrets and variables -> Actions -> New repository secret。添加以下三个secret变量：

VPS_SSH_KEY #刚刚复制的key
VPS_HOST #输入你的vpsip：123.45.67.89
VPS_USER #一般为root

如果不知道VPS_USER,命令行:

whoami

4. 创建 Workflow 文件

在GitHub项目的action页面或者 在你的 Astro 项目根目录创建 .github/workflows/deploy.yml：

name: Deploy to VPS

on:
  push:
    branches: [ master ] # 监听 master 分支的 push 事件

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      # 1. 拉取代码
      - name: Checkout
        uses: actions/checkout@v4

      # 2. 安装 Node.js
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      # 3. 安装依赖并构建
      - name: Install and Build
        run: |
          npm ci
          npm run build
        # 构建完成后，静态文件会在 ./dist 目录下

      # 4. 部署到 VPS (使用 rsync)
      - name: Deploy via rsync
        uses: easingthemes/ssh-deploy@main
        with:
          SSH_PRIVATE_KEY: ${{ secrets.VPS_SSH_KEY }}
          ARGS: "-rlgoDzvc -i"
          SOURCE: "dist/"  # 本地构建产物目录
          REMOTE_HOST: ${{ secrets.VPS_HOST }}
          REMOTE_USER: ${{ secrets.VPS_USER }}
          TARGET: "/var/www/my-blog/dist/" # VPS 上的目标目录
          EXCLUDE: "/node_modules/"

---

第四阶段：日常写作流程

现在，你的全自动化流程已经打通了。以后的日常只需要：

1. 写文章：

   • 在 src/content/blog/ 新建 Markdown。
   • 输入 fm + Tab 自动生成 Frontmatter。
   • 写内容，插图（使用 ../../assets/xxx.jpg）。

2. 提交代码：

   git add .
   git commit -m "New post: My Trip to Osaka"
   git push origin main

3. 喝咖啡：

   • GitHub Actions 会自动触发。
   • 它会安装依赖 -> npm run build -> 生成 dist -> 通过 SSH 将新文件覆盖到 VPS。
   • 刷新你的网站，新文章已经上线了。

---

💡 进阶优化建议

图片优化： 由于我们使用了 Astro 的 src/assets 和 image() Schema，Astro 在构建时会自动压缩图片并转换为 WebP 格式，无需额外配置，这就是通过 GitHub Actions 构建的好处（如果是本地构建再上传，你就得自己负责构建这一步）。