UD5工具箱
Q: GitHub Actions 工作流中哪些字段是必需的？
A: GitHub Actions 工作流配置中，必须定义的顶级字段包括：name（工作流名称，可选但推荐）；on（触发事件，必需）；jobs（作业定义，必需）。在 jobs 下的每个作业中，必须包含 runs-on（运行器选择，必需）和 steps（步骤定义，必需）。其他字段如 env、permissions、defaults 等都是可选的。缺少必需字段会导致工作流无法被 GitHub 识别和执行。
Q: runs-on 和 steps 字段为什么是必需的？
A: runs-on 指定作业在什么类型的运行器上执行，没有运行器就无法执行任何操作。GitHub 提供多种运行器类型，如 ubuntu-latest、windows-latest、macos-latest 等，也可以使用自托管运行器标签。steps 定义了作业要执行的具体操作，包括运行命令或调用 Action。一个作业至少需要一个 step，否则该作业没有任何实际操作。这两个字段是 GitHub Actions 工作流能够执行的最低要求。
Q: 如何避免 YAML 缩进错误？
A: 避免 YAML 缩进错误的关键是保持一致的缩进风格。推荐使用 2 个空格作为缩进单位，不要使用制表符。在编辑器中启用显示空白字符功能可以帮助识别缩进问题。常见错误包括：混用空格和制表符；缩进数量不一致（如有的用 2 空格，有的用 4 空格）；列表项的短横线后忘记加空格。使用支持 YAML 语法高亮的编辑器（如 VS Code）可以有效减少缩进错误。此外，使用本工具验证配置可以提前发现 YAML 格式问题。
Q: actions/checkout 的正确用法是什么？
A: actions/checkout 是用于检出仓库代码的 Action，几乎所有工作流都需要使用。基本用法为：uses: actions/checkout@v4。默认情况下它会检出触发工作流的提交。常用参数包括：ref指定要检出的分支或提交；token使用自定义令牌进行认证（私有仓库需要）；fetch-depth设置 Git 历史深度，默认为 1（浅克隆），设为 0 可获取完整历史。对于大多数场景，使用默认配置即可满足需求。
Q: permissions 字段有什么作用？如何正确配置？
A: permissions 字段用于控制 GITHUB_TOKEN 的访问权限范围。按照最小权限原则，应该只授予工作流实际需要的权限。例如，如果工作流只需要读取代码，可以设置 permissions: contents: read。在工作流级别设置 permissions 会作为所有作业的默认值；在作业级别设置会覆盖工作流级别的配置。设置 permissions: {} 可以完全禁用 GITHUB_TOKEN 权限。正确配置 permissions 可以降低因令牌泄露导致的安全风险。
Q: 如何调试失败的 GitHub Actions 工作流？
A: 调试 GitHub Actions 工作流可以从以下几个方面入手：首先查看工作流日志，定位失败的步骤和错误信息；使用 step 级别的 if 条件或 continue-on-error: true 进行条件执行或忽略错误；在 Workflow 中添加 echo 步骤输出调试信息；使用 act 工具在本地运行 GitHub Actions 进行调试；检查环境变量和 Secrets 是否正确配置；验证工作流语法是否正确。对于复杂的工作流，建议先在小范围测试验证后再应用到完整的 CI/CD 流程。
Q: GitHub Actions 支持哪些触发事件类型？
A: GitHub Actions 支持丰富的触发事件类型，主要包括：push推送到指定分支；pull_requestPR 创建或更新；schedulecron 定时触发；workflow_dispatch手动触发；release发布新版本；issuesIssue 操作；issue_commentIssue 评论；workflow_run其他工作流完成后触发；repository_dispatch通过 API 自定义事件触发。每种事件都可以配置分支过滤（branches）和路径过滤（paths），实现更精确的触发控制。
Q: needs 字段如何实现 Job 之间的依赖？
A: needs 字段用于定义 Job 之间的执行依赖关系。当 Job B 设置了 needs: [job-a] 时，Job B 会等待 Job A 执行完成后才开始执行。如果 Job A 失败，Job B 默认不会执行（除非设置了 if: always()）。多个依赖用数组表示，如 needs: [job-a, job-b]，表示需要等待所有依赖 Job 完成。needs 字段常用于多阶段流水线：先执行构建 Job，成功后执行测试 Job，测试通过后执行部署 Job。合理使用 needs 字段可以实现复杂的工作流编排。