VSCode 无法直接运行 GitHub Actions，仅支持 YAML 语法检查与跳转；本地验证需借助 act 工具模拟执行、Docker 复现环境、手动对齐依赖和变量。
VSCode 里直接运行 GitHub Actions 工作流？不行，但可以模拟
GitHub Actions 只能在 GitHub 托管的 runner 上执行，vscode 本身不提供 Actions 运行时。所谓“调试”，实际是本地验证 YAML 语法 + 模拟触发逻辑 + 复现关键步骤。别指望点一下就跑通 .github/workflows/ci.yml，那是误解。
真正能做的，是把工作流拆成可本地复现的单元：比如用 shellcheck 验证脚本、用 docker run 启动相同基础镜像、手动执行 npm test 看是否和 job 中一致。
- 用
act（开源 CLI）在本地近似运行 workflow —— 它会拉取 action 的 Docker 镜像并执行，最接近真实环境 -
vscode自带的 YAML 支持能高亮语法、跳转到uses: actions/checkout@v4的定义（需装redhat.vscode-yaml插件） - 别依赖 VSCode 的“调试”按钮去跑 Actions；它没有对应调试器，点了也没反应
用 act 在本地测试 .github/workflows/*.yml
act 是目前最实用的本地验证工具，它不是模拟器，而是真拉镜像、真 mount workspace、真跑 steps。但它默认用轻量级 runner（nektos/act-environments-ubuntu:18.04），和 GitHub 官方 ubuntu-latest 有细微差异。
- 安装：
brew install act（macOS）、sudo apt install act（Ubuntu 24.04+），或用curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash - 运行指定 workflow：
act -W .github/workflows/test.yml -j build（-j指定 job 名） - 常见失败原因：本地没装
dockerd（act必须依赖 Docker）、GITHUB_TOKEN缺失（某些 action 如actions/github-script会报错，加-s GITHUB_TOKEN=xxx临时绕过） - 注意
act不支持所有官方 runner 特性，比如container内嵌services或 matrix strategy 的完整展开，遇到就切回 GitHub Actions 查日志
VSCode 插件能帮你检查什么、不能帮你检查什么
插件解决的是“写得对不对”，不是“跑得通不通”。redhat.vscode-yaml + github-actions-vscode 组合最实用，但能力边界很明确。
- 能检查：
on:下的事件名拼写（如pull_request_target是否有效）、uses:的 action 路径是否存在公开仓库、env:键名是否重复 - 不能检查：
run:里的 shell 命令是否真能在ubuntu-latest上执行（比如用了gawk但没apt install）、secrets.GITHUB_TOKEN权限是否足够、matrix 变量是否被正确引用为${{ matrix.node }} - 提示错误
Unexpected token in JSON at position X？大概率是 YAML 缩进错位或用了制表符（Tab），VSCode 默认显示空格数，打开右下角状态栏看是不是 “Spaces: 2” 变成了 “Tab Size: 2”
本地复现 CI 环境的关键三步
很多问题不是 YAML 写错了，而是本地开发环境和 CI 环境不一致。与其猜，不如直接对齐。
- 查 GitHub 官方 runner 镜像预装软件列表：访问
https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md，对照你用的runs-on: ubuntu-22.04 - 在本地启动等效容器：
docker run --rm -it -v $(pwd):/workspace -w /workspace ghcr.io/actions/runner-images:ubuntu-22.04，然后手动执行 job 里的run:命令 - 复制 CI 中的关键环境变量：比如
NODE_VERSION=18，就在本地export NODE_VERSION=18后再跑nvm use，别只靠.nvmrc
越早把本地环境拉到和 CI 一致，越少出现“我本地好好的，CI 报错”的情况。这不是多此一举，是省掉反复 push → 等 2 分钟 → 看 log → 改 → push 的唯一办法。
