更新日志 - Web3 自学指南

[giscus[bot]]

更新历史 - Web3 自学指南

https://lifefindsitsway.wiki/changelog/

[lifefindsitsway]

当用户配置了 GitHub Actions 部署工作流，并将本地仓库的更改提交到 GitHub 远程仓库之后，GitHub Actions 会自动执行一系列操作来构建并部署网站，过程大致如下：

（1）本地提交并推送更改
● 本地提交：在本地对项目（如 MkDocs 项目）进行更改后，通过 git commit 命令将更改提交到本地 Git 仓库：
git add .
git commit -m "Update documentation"
● 推送到远程仓库：接着，使用 git push 命令将本地提交推送到 GitHub 仓库的 main 分支（或指定的其他分支）：
git push origin main

（2）触发 GitHub Actions 工作流
当更改被推送到远程仓库时，GitHub 会检测到新的提交，并根据配置的工作流文件（如 .github/workflows/deploy.yml），自动触发 GitHub Actions 工作流。
工作流文件会定义在什么情况下（如推送到 main 分支时）触发哪些操作。通常，这个文件的配置会包含如下内容：

on:
  push:
    branches:
      - main  # 当推送到 main 分支时触发工作流

关键步骤：
● GitHub 触发工作流：当检测到推送到 main 分支时，GitHub Actions 会自动启动工作流；
● 工作流执行环境：GitHub Actions 运行在虚拟机环境中，通常使用的是 ubuntu-latest 这样的基础环境，工作流的每个步骤都会在这个环境中执行；

（3）工作流执行步骤
以典型的 MkDocs 网站部署为例，GitHub Actions 工作流文件可能如下：

name: Deploy documentation to GitHub Pages
on:
  push:
    branches:
      - master
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x
      
      - run: pip3 install -U -r requirements.txt
      
      - name: Build the documentation
        run: |
          mkdocs build
        
      - name: Deploy to GitHub Pages
        run: |
          mkdocs gh-deploy --force
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # GitHub 自动提供的 token

工作流的每一步详细解释：

1. Checkout code（检出代码）：
   ○ 使用 actions/checkout 将用户仓库的代码检出到 GitHub Actions 的虚拟环境中，以便在其上运行接下来的构建步骤；
   ○ fetch-depth: 0 确保获取完整的提交历史，这对一些项目依赖完整的 git 历史构建文档可能有用。
2. Set up Python（设置 Python 环境）：
   ○ 使用 actions/setup-python 动作来配置适当版本的 Python 环境，通常是 3.x；
   ○ 这一步是为了能够在虚拟环境中安装依赖并运行 MkDocs 构建命令。
3. Install dependencies（安装依赖）：
   ○ 使用 pip 安装 mkdocs-material 等项目所需的 Python 依赖包，可以根据需要添加更多的依赖。
4. Build the documentation（构建文档）：
   ○ 运行 mkdocs build 命令，将 docs 目录中的 Markdown 文档生成静态 HTML 文件。输出会存放在 site/ 目录下。
5. Deploy to GitHub Pages（部署到 GitHub Pages）：
   ○ 使用 mkdocs gh-deploy --force 命令将 site/ 目录中的静态网站部署到 gh-pages 分支；
   ○ GITHUB_TOKEN 是 GitHub 自动生成的 token，用于授权 Actions 推送更改到 gh-pages 分支，完成 GitHub Pages 的部署。

（4）部署完成
● 推送到 gh-pages 分支：mkdocs gh-deploy 命令会自动将构建好的静态文件推送到 GitHub 仓库的 gh-pages 分支，这个分支就是 GitHub Pages 用来托管静态网站的分支；
● GitHub Pages 自动更新：一旦 gh-pages 分支有新的更改，GitHub Pages 服务会自动检测并更新托管的站点。用户可以通过自定义域名或 https://yourusername.github.io/repository-name/ 访问最新版本的站点。

（5）结果验证
● 本地测试：在执行 GitHub Actions 前，可以在本地通过 mkdocs serve 来测试站点，确保没有问题；
● 远程验证：GitHub Actions 执行完毕后，可以通过访问指定的 GitHub Pages URL 来查看部署后的结果，确保网站已经正确更新并且所有内容正常显示。

（6）问题排查
如果在这个流程中遇到问题，可以通过以下方式进行排查：
● 查看 GitHub Actions 日志：在 GitHub 仓库的 Actions 页面，选择你执行的工作流，查看详细日志，确保每一步都执行成功；
● 确保 gh-pages 分支可用：检查 gh-pages 分支，确认文档内容已经正确推送到该分支；
● 检查 GitHub Pages 设置：确保你的 GitHub Pages 设置为从 gh-pages 分支读取文件，并且没有错误配置。

总结

1. 本地提交并推送更改；
2. GitHub Actions 自动触发；
3. 检出代码，安装依赖，构建并部署站点；
4. 站点部署到 GitHub Pages；
5. 通过 GitHub Pages 访问更新后的站点。