必须安装github官方扩展、置于.github/workflows/路径、切换语言模式为github actions，三步缺一不可；red hat yaml等扩展会冲突导致失效。

装对扩展、放对位置、配对语言模式，三步到位。其他花哨功能全是锦上添花，这三步没走稳，补全、校验、跳转全失效。

必须安装 GitHub Actions 官方扩展，且卸载 Red Hat YAML

VSCode 默认不识别 .yml 文件里的 on、jobs、uses 是 GitHub Actions 特有字段，只当普通 YAML 处理。官方 GitHub Actions 扩展（发布者是 GitHub）注册了 github-actions 语言模式，才能触发语义校验和补全。

• 在扩展市场搜 GitHub Actions，认准发布者为 GitHub 的那个
• 如果已装过 Red Hat YAML 或其他 YAML 类扩展，必须先禁用或卸载——它们会劫持 .yml 文件的语言模式，导致 GitHub Actions 扩展完全不生效
• 安装后务必重启 VSCode，或手动按 Ctrl+Shift+P → Change Language Mode → 选 GitHub Actions，否则文件仍被识别为纯 YAML

工作流文件必须放在 .github/workflows/ 下

扩展只监听标准路径。放错位置，哪怕语法完全正确，也不会激活任何校验或补全。

GitHub Actions Failure Spike Audit

通过对比近期与基线运行窗口，按工作流分组检测 GitHub Actions 失败率突增。

下载

• 路径必须是项目根目录下的 .github/workflows/ci.yml（注意 . 开头、大小写、斜杠方向）
• 文件名可以是 ci.yml、test.yaml 等，但后缀只能是 .yml 或 .yaml
• 如果放到了 config/workflow.yml 这类非标路径，扩展不会扫描，gha 代码片段也无效

uses: 补全只对公开 action 生效

扩展能提示 actions/checkout@v4 的 token、submodules 等输入项，是因为它去 GitHub 上拉取了该仓库公开的 action.yml。私有或本地 action 不在此列。

• 用 uses: actions/checkout@v4 或 uses: docker/setup-qemu-action@v3 这类官方/公开 action 时，悬停或输入 with: 后会自动列出合法字段
• 用 uses: myorg/private-action@main 时，只要该仓库设为 private，扩展就拿不到 action.yml，补全空白
• 用 uses: ./actions/my-build 这种本地路径，扩展完全不解析，零提示

别指望 VSCode 检查运行逻辑是否通

它只管“写得合规矩”，不管“跑得通不通”。很多报错要等 act 本地跑或推到 GitHub 才暴露。

• 语法检查不拦 run: gawk '{print $1}' file.txt —— 即使 ubuntu-latest 镜像里根本没装 gawk
• 不验证 ${{ secrets.MY_TOKEN }} 是否真在仓库 Settings → Secrets 中配置过
• 不检查 matrix.node 是否被正确引用为 ${{ matrix.node }}（少一对 {{}} 就静默失效）
• 分支保护规则、workflow permissions 等权限层问题，VSCode 完全无感

最易被忽略的是：扩展和 act 是两套系统。扩展保你写得规范，act 保你跑得接近真实——缺一不可，但谁也替代不了谁。