安装GitHub Actions官方插件后必须做的三件事：一、确保项目根目录存在.github/workflows/及合法.yml文件；二、保证YAML语法正确，缩进对齐、必需字段不缺失；三、VSCode需以Git仓库为工作区打开，否则插件无法识别上下文。
VSCode 本身不运行 GitHub Actions，但能让你在编辑器里写得准、试得快、看得清——关键不是“能不能跑”，而是“怎么避免推上去才发现错”。
安装 GitHub Actions 官方插件后必须做的三件事
插件装完不等于可用。它依赖三个前提才能真正起作用：
- 项目根目录下存在
.github/workflows/目录，且至少有一个.yml文件（如ci.yml） - 该 YAML 文件语法合法：缩进对齐、冒号后有空格、
on/jobs/steps等顶层字段不能缺 - VSCode 当前工作区已打开该 Git 仓库（不是只打开单个文件），否则插件无法识别上下文
常见错误现象：GitHub Actions: Invalid workflow file 出现在状态栏，但没提示哪一行；或者侧边栏完全不显示 Workflows 列表。此时先检查 .github 是否拼错（注意开头的点）、workflows 是否小写、YAML 文件是否保存（未保存的临时文件不会被扫描）。
用 gha 代码片段快速生成合法结构
手动敲 name、on、jobs 极易漏字段或缩进错位。插件预置了代码片段，输入 gha + Tab 就能展开标准模板：
- 会自动补全
on: [push]、jobs:和一个带runs-on的 job - 光标停在
on字段，方便你立刻改成pull_request或加scheduler - 所有缩进按 GitHub Actions Schema 要求对齐（2 空格层级），避免
Expected a mapping类报错
别改缩进方式——比如把 steps: 缩进从 2 格改成 4 格，会导致后续 - run: 被解析为顶级字段而失败。
使用约定式提交（Conventional Commits）从 Git 历史记录中生成结构化变更日志，支持多种格式、AI 增强型描述以及可自定义的范围……
act 本地模拟执行时最常踩的坑
act 是唯一能在不 push 的情况下验证 workflow 逻辑的工具，但它对环境很敏感：
- 默认使用
ubuntu-latest镜像，若 workflow 中指定了runs-on: macos-latest，act会直接报错不兼容 - 多行脚本用
|声明时，后续每行必须比|所在行**多缩进至少 2 格**，否则act解析失败并报could not find expected ':' - 如果 workflow 用了自定义 action（如
./.github/actions/my-action），act默认不加载本地路径，需加-P ./path=.参数显式映射
推荐在 .vscode/tasks.json 里配一个 task：
{
"label": "act: test build",
"type": "shell",
"command": "act -j build",
"group": "build",
"presentation": {
"echo": true,
"reveal": "always"
}
}这样按 Ctrl+Shift+P → Tasks: Run Task 就能一键触发，不用记命令参数。
调试日志看不到完整输出？检查 token 权限
插件侧边栏点击 ▶ Run workflow 后，点 job 查看日志，如果只显示 “Starting…” 就卡住，或提示 Failed to fetch logs，大概率是 GitHub Token 权限不足：
- 必须勾选
repo和workflow两个 scope，缺一不可 - token 不能是 classic 类型的旧 token（2025 年后新创建的默认是 fine-grained）
- 设置后要重启 VSCode 或执行
GitHub Actions: Refresh Workflow Runs才生效
另一个容易被忽略的点：日志里出现 ##[error]Resource not accessible by integration，通常是因为 workflow 文件里用了 secrets.GITHUB_TOKEN，但当前分支保护规则禁止该 token 访问私有仓库内容——这问题在编辑器里看不出，只能靠实际运行日志暴露。
