Gridea自动化部署：GitHub Actions实现CI/CD流程

2026-02-05 05:34:25作者：柯茵沙

引言：告别繁琐部署，拥抱自动化

你是否还在为Gridea博客的手动部署流程感到困扰？每次写完文章都要手动执行构建和推送命令，不仅耗时还容易出错。本文将带你通过GitHub Actions实现Gridea博客的全自动CI/CD流程，让你专注于创作而非部署。

读完本文后，你将能够：

理解Gridea的部署原理
配置GitHub Actions工作流文件
实现代码提交后自动构建和部署博客
解决常见的自动化部署问题

Gridea部署原理简析

Gridea作为一个静态博客写作客户端，其核心原理是将Markdown文件渲染为静态HTML页面，然后通过Git将生成的文件推送到GitHub Pages等平台。这一过程在src/server/deploy.ts中有详细实现。

主要部署流程包括：

检查远程仓库连接
初始化Git仓库（如未初始化）
添加并提交更改
推送到远程仓库

Gridea支持多种部署平台，包括GitHub、Coding和Gitee，这在部署模块的代码中可以看到：

this.platformAddress = ({
  github: 'github.com',
  coding: 'e.coding.net',
  gitee: 'gitee.com',
} as any)[setting.platform || 'github']

准备工作：环境与配置

在开始配置GitHub Actions之前，需要确保你已经完成以下准备工作：

1. 安装Gridea并初始化博客

如果你还没有安装Gridea，可以从官方渠道下载最新版本。安装完成后，按照引导初始化你的博客项目。Gridea支持Windows、macOS和Linux系统，满足不同用户的需求。

2. 准备GitHub仓库

确保你的博客源代码已经托管在GitHub仓库中。如果还没有，可以通过以下命令初始化并推送到GitHub：

git clone https://gitcode.com/gh_mirrors/gr/gridea
cd gridea
git add .
git commit -m "Initial commit"
git push origin main

3. 获取访问令牌

为了让GitHub Actions有权限操作你的仓库，需要创建一个Personal Access Token (PAT)：

登录GitHub，进入Settings > Developer settings > Personal access tokens
点击"Generate new token"
勾选repo权限
生成并保存令牌，后面会用到

配置GitHub Actions工作流

创建工作流文件

在你的仓库中创建.github/workflows/gridea-deploy.yml文件，这个文件将定义CI/CD流程。

工作流配置详解

以下是一个完整的Gridea自动化部署工作流配置：

name: Gridea Auto Deploy

on:
  push:
    branches: [ main ]
    paths:
      - 'posts/**'
      - 'themes/**'
      - 'config.json'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        
    - name: Install dependencies
      run: npm install
      
    - name: Build Gridea project
      run: npm run build
      
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v4
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./public
        publish_branch: gh-pages

这个配置文件定义了以下关键部分：

触发条件：当main分支上的posts、themes目录或config.json文件发生变更时触发
工作流程：
- 检出代码
- 设置Node.js环境
- 安装依赖
- 构建项目
- 部署到GitHub Pages

配置密钥

在GitHub仓库的"Settings > Secrets > Actions"中添加以下密钥：

GH_TOKEN：之前创建的Personal Access Token

自动化部署流程解析

触发机制

GitHub Actions工作流会在满足以下条件时自动触发：

代码推送到main分支
变更涉及posts目录（文章内容）、themes目录（主题文件）或config.json（配置文件）

这种设计确保只有相关变更才会触发部署，减少不必要的构建。

构建过程

构建步骤主要依赖Gridea本身的构建命令。在package.json中可以看到Gridea定义的各种脚本命令，包括构建相关的命令。

部署过程

部署步骤使用了peaceiris/actions-gh-pages这个GitHub Action，它会将构建生成的静态文件推送到gh-pages分支，而GitHub Pages会自动从这个分支部署你的博客。

常见问题与解决方案

部署失败：权限问题

如果遇到权限相关的错误，通常是因为访问令牌配置不正确。请检查：

令牌是否具有足够的权限
密钥是否正确添加到GitHub仓库的Secrets中
工作流文件中是否正确引用了密钥

构建错误：依赖问题

Gridea项目在package.json中定义了所有依赖。如果构建过程中出现依赖错误，可以尝试：

# 清除npm缓存
npm cache clean --force

# 重新安装依赖
rm -rf node_modules package-lock.json
npm install

部署后页面未更新

如果部署成功但页面没有更新，可能是因为：

GitHub Pages缓存问题，可以尝试强制刷新浏览器
工作流中的publish_dir配置不正确，确保指向Gridea生成静态文件的目录
检查是否有构建错误被忽略

高级配置：自定义与优化

多环境部署

你可以扩展工作流配置，实现多环境部署，例如同时部署到GitHub Pages和Gitee Pages：

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      # ... 前面的步骤省略 ...
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages
          
      - name: Deploy to Gitee Pages
        uses: yanglbme/gitee-pages-action@main
        with:
          gitee_username: ${{ secrets.GITEE_USERNAME }}
          gitee_password: ${{ secrets.GITEE_PASSWORD }}
          gitee_repo: your-gitee-repo
          branch: gh-pages
          dir: ./public

定时部署

如果需要定期部署（例如定时同步某些外部资源），可以添加定时触发：

on:
  push:
    # ... 保持不变 ...
  schedule:
    - cron: '0 0 * * *'  # 每天午夜执行

部署通知

可以添加部署结果通知，例如发送到Slack或Email：

- name: Send notification
  if: always()
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    fields: repo,message,commit,author,action,eventName,ref,workflow
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}