GitHub Actions 新手友好指南

轻松构建项目可执行文件

目标：通过 Fork（复制）项目的 GitHub 仓库，并利用 GitHub 的自动化构建服务 (GitHub Actions)，自动将最新的项目源代码编译打包成你电脑可以直接运行的程序文件 (.exe, .app)。

适合人群：需要项目的最新可执行文件，但不想或不会自己手动编译代码的用户。

核心步骤概述：

1. 准备：登录 GitHub，找到项目仓库。

2. Fork：创建你自己的项目副本。

3. 配置 Actions 权限：允许你的副本运行自动化构建。

4. 启动构建任务：选择分支并触发构建流程。

5. 等待与下载：监控构建状态，成功后下载文件。

6. 更新（后续构建）：保持你的副本与原始项目同步。

0. 准备工作

• 确保你有一个 GitHub 账号；如果没有，请先注册。

• 登录你的 GitHub 账号。

• 使用浏览器打开你要构建的项目 GitHub 仓库页面。(例如，项目地址通常像 https://github.com/作者名/项目名)

1. Fork (复制) 项目仓库

• 目的：在你的 GitHub 账号下创建一个原项目的独立副本。你只能在自己的副本上运行自动化构建。

• 操作：

      1. 在项目的官方仓库页面右上角，找到 Fork 按钮（分叉图标或写着 "Fork" 的文字按钮）。

      2. 点击 Fork 按钮。

      3. 这时会弹出一个创建 Fork 的窗口。非常重要：

          取消勾选 Copy the master branch only。

          原因：项目有多个开发分支（如 develop）。取消勾选可以确保你 Fork 时复制了所有分支，这样你之后才能选择 develop 分支或其他分支进行构建。如果只复制主分支 (master)，你可能无法构建开发中的最新功能。

      4. 点击窗口底部的 Create fork 按钮。

• 等待：GitHub 需要一点时间创建你的副本。页面会自动跳转到属于你自己的 GitHub 账号下的新仓库页面（地址类似 https://github.com/你的用户名/项目名）。这就是你的 Fork 仓库。

2. 配置 GitHub Actions 权限

• 目的： 默认情况下，Fork 仓库的 Actions 权限可能受限。我们需要允许它运行所有自动化脚本（包括构建脚本）。

• 操作：

1. 在你的 Fork 仓库页面（上一步跳转到的页面），点击顶部的 Settings 选项卡。

2. 在左侧菜单栏中找到 Actions 并点击。

3. 在展开的 Actions 子菜单中，点击 General。

4. 向下滚动到 Workflow permissions 区域。

5. 找到 Allow all actions and reusable workflows 这个选项，确保它被选中。

6. 滚动到页面底部或找到 Save 按钮，点击保存设置。

3. 启用并运行构建工作流

• 目的：找到并启动负责编译打包的自动化任务。

• 操作：

1. 在你的 Fork 仓库页面，点击顶部的 Actions 选项卡。

2. 如果你第一次访问仓库的 Actions 页面，你会看到一个介绍页面和一个按钮写着 I understand my workflows, go ahead and enable them。点击这个按钮。这表示你同意在这个仓库上运行工作流。之后再来就不需要点这个了。

3. 在 Actions 页面，你会看到左侧有一个工作流列表。找到名为 构建可执行文件 的工作流。点击它。

4. 进入该工作流的页面后，在右上角找到一个 Run workflow 下拉按钮。

5. 点击 Run workflow。

6. 通常会弹出一个小窗口让你选择：

       Branch (分支)：点击下拉菜单，选择你想要基于哪个分支的代码进行构建。


           master：相对稳定的版本。

           develop：包含最新的功能和修复，但也可能不够稳定。

7. 确认选择好分支后，点击小窗口里的绿色 Run workflow 按钮。

4. 等待构建完成并下载文件

• 目的： 监控自动化构建过程，并在成功后获取生成的可执行文件。

• 操作：

1. 点击 Run workflow 后，页面会自动跳转到 当前运行的工作流实例 列表页。你能看到一个刚刚启动的、状态是 Queued (排队中) 或 In progress (进行中) 的新条目。

2. 耐心等待：构建过程可能需要几分钟。

3. 观察状态：

       黄色图标：表示正在运行。

       红色图标：表示构建失败。别慌！点击该运行条目查看详细的日志（特别是红色的错误信息），这有助于排查问题（常见问题见下方“注意事项”）。

       绿色图标：表示构建成功！

4. 下载文件：

   1. 点击状态为绿色图标的运行条目。

   2. 进入该次运行的详情页面。

   3. 滚动到页面底部附近，寻找 Artifacts (制品) 区域。

   4. 在 Artifacts 区域，你会看到多个文件名，点击你需要的平台对应的文件名。

   5. 浏览器会自动开始下载一个 .zip 压缩包，里面就包含了你需要的可执行文件。下载完成后解压即可使用。

5. 后续构建（当原项目更新后）

• 目的：获取原项目最新代码编译出来的文件。

• 重要：你的 Fork 仓库是原项目在某个时间点的快照。当原项目作者更新了代码（修复 Bug，增加新功能），你的 Fork 仓库并不会自动更新！

• 操作：

1. 在运行新的构建 (Run workflow) 之前，你需要先同步 (Sync) 你的 Fork 仓库，获取原项目的最新代码。

2. 在你的 Fork 仓库页面，点击顶部的 Code 选项卡。

3. 在文件列表上方，你会看到一个提示，你的分支落后 (behind) 原项目多少个提交，旁边有一个 Sync fork 按钮。点击 Sync fork，再点击 Update branch。
   

4. 等待同步完成。

5. 同步完成后，再回到 Actions 选项卡，选择 构建可执行文件 工作流，点击 Run workflow，选择分支（通常是 develop 或 master），启动新的构建。

新手常见问题与注意事项

• 为什么需要 Fork？GitHub Actions 默认不能在别人的仓库里直接运行（除非你是合作者）。Fork 是创建你自己的副本，你对自己的副本有完全控制权。

• 为什么要取消 Copy the master branch only？确保你能构建 develop 分支（或其他非主分支）上的最新代码。项目的新功能先在 develop 分支开发。

• 构建失败了（红色 ×）怎么办？
  

      点击失败的运行条目！ 这是最重要的。

      仔细阅读 红色的错误信息，它通常会告诉你哪里出错了。

      把错误信息复制下来，可以去项目的 Issues 区搜索是否有相同问题，或者开一个新 Issue 询问（附上错误日志）。

• 找不到 Artifacts？

      确认构建确实成功（绿色 ✓）。

      滚动页面到底部仔细找。

• 安全提示：运行 Allow all actions and reusable workflows 意味着你信任该项目配置的 Actions 脚本。通常开源项目是安全的，但理论上脚本可以做很多事情。请确保你 Fork 的是可信赖的官方项目仓库。

本指南适用于开源项目：DouK-Downloader（历史名称：TikTokDownloader）、XHS-Downloader、KS-Downloader

开源项目 GitHub 仓库地址

• DouK-Downloader：https://github.com/JoeanAmier/TikTokDownloader

• XHS-Downloader：https://github.com/JoeanAmier/XHS-Downloader

• KS-Downloader：https://github.com/JoeanAmier/KS-Downloader