从零配置 GitHub Actions CI/CD 自动化部署

前言#

最近为我的博客配置了 GitHub Actions CI/CD，实现了代码推送后自动构建和部署。这篇文章记录整个配置过程，希望能帮助到有同样需求的朋友。

什么是 CI/CD#

CI (Continuous Integration) 持续集成：代码合并后自动构建和测试 CD (Continuous Deployment) 持续部署：构建通过后自动部署到服务器

对于静态博客来说，这意味着：

本地写好文章，push 到 GitHub
GitHub Actions 自动构建
构建成功后自动部署到服务器
全程无需手动操作

准备工作#

服务器环境#

Linux 服务器（我的是 Alibaba Cloud Linux）
已安装 Nginx 或其他 Web 服务器
确保有 SSH 访问权限

安装必要软件#

在服务器上安装 rsync（用于文件同步）：

1
# CentOS/RHEL/Alibaba Cloud Linux
2
sudo yum install -y rsync
3

4
# Ubuntu/Debian
5
sudo apt-get update && sudo apt-get install -y rsync

GitHub 仓库配置#

在 GitHub 创建仓库，上传博客源码
确保仓库有构建脚本（如 pnpm build）

配置 GitHub Actions#

1. 创建 Workflow 文件#

在仓库根目录创建 .github/workflows/deploy.yml：

1
name: Deploy to Server
2

3
on:
4
  push:
5
    branches: [ main ]
6
  pull_request:
7
    branches: [ main ]
8

9
env:
10
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
11

12
jobs:
13
  build:
14
    runs-on: ubuntu-latest
15

16
    steps:
17
    - name: Checkout
18
      uses: actions/checkout@v4
19

20
    - name: Setup Node.js
21
      uses: actions/setup-node@v4
22
      with:
23
        node-version: '22'
24

25
    - name: Setup pnpm
26
      uses: pnpm/action-setup@v2
27
      with:
28
        version: 9
29

30
    - name: Get pnpm store directory
31
      shell: bash
32
      run: |
33
        echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
34

35
    - name: Setup pnpm cache
36
      uses: actions/cache@v4
37
      with:
38
        path: ${{ env.STORE_PATH }}
39
        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
40
        restore-keys: |
41
          ${{ runner.os }}-pnpm-store-
42

43
    - name: Install dependencies
44
      run: pnpm install
45

46
    - name: Build
47
      run: pnpm build
48

49
    - name: Deploy to Server
50
      if: github.ref == 'refs/heads/main'
51
      uses: easingthemes/ssh-deploy@v5.0.3
52
      with:
53
        SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
54
        ARGS: "-rltgoDzvO --delete"
55
        SOURCE: "dist/"
56
        REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
57
        REMOTE_USER: ${{ secrets.REMOTE_USER }}
58
        REMOTE_PORT: ${{ secrets.REMOTE_PORT }}
59
        TARGET: ${{ secrets.REMOTE_TARGET }}
60
        EXCLUDE: "/dist/, /node_modules/"

2. 配置 Secrets#

在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加以下 secrets：

Secret	说明
`SSH_PRIVATE_KEY`	服务器 SSH 私钥
`REMOTE_HOST`	服务器地址
`REMOTE_USER`	SSH 用户名
`REMOTE_PORT`	SSH 端口
`REMOTE_TARGET`	部署目标路径

生成 SSH 密钥#

在本地生成密钥对：

1
ssh-keygen -t ed25519 -C "github-actions" -f ~/.ssh/github_actions

将公钥添加到服务器的 ~/.ssh/authorized_keys：

1
cat ~/.ssh/github_actions.pub >> ~/.ssh/authorized_keys

将私钥内容复制到 GitHub Secrets 的 SSH_PRIVATE_KEY。

遇到的问题与解决#

问题 1：Node.js 版本警告#

GitHub Actions 提示 Node.js 20 actions 将在 2026年6月后弃用。

解决：添加环境变量强制使用 Node.js 24：

1
env:
2
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

问题 2：类型检查失败#

Astro 的 astro check 报告类型错误，导致构建失败。

解决：跳过类型检查，只执行构建：

1
- name: Build
2
  run: pnpm build  # 不运行 pnpm astro check

问题 3：服务器缺少 rsync#

部署时报错 rsync: command not found。

解决：在服务器上安装 rsync（见准备工作）。

问题 4：SSH 连接被拒绝#

部署时无法连接到服务器。

解决：

检查 SSH 密钥是否正确配置
确认服务器防火墙允许 GitHub Actions IP
验证端口是否正确

优化配置#

跳过不必要的构建#

如果只想在代码文件变更时触发构建，可以添加路径过滤：

1
on:
2
  push:
3
    branches: [ main ]
4
    paths:
5
      - 'src/**'
6
      - 'public/**'
7
      - 'package.json'
8
      - 'pnpm-lock.yaml'

多 Node.js 版本测试#

如果需要测试多个 Node.js 版本：

1
strategy:
2
  matrix:
3
    node: [ 22, 23 ]

但对于个人博客，通常只需要一个版本即可。

验证部署#

配置完成后，push 代码到 main 分支，观察 GitHub Actions 运行状态：

进入仓库的 Actions 标签
查看 workflow 运行状态
绿色 ✅ 表示成功

部署成功后，访问博客域名查看效果。

总结#

通过 GitHub Actions 实现自动化部署后，博客的发布流程变得非常简单：

本地编写文章
git push origin main
等待 1-2 分钟
文章自动上线

不再需要手动构建、上传文件，大大提升了写作效率。

参考链接#

本文记录于 2026-03-12，配置环境：Astro + pnpm + GitHub Actions + Linux 服务器