github actions 配置文件必须放在 .github/workflows/ 目录下，后缀为 .yml 或 .yaml，路径大小写敏感；触发需正确配置 on: push 的分支、路径和标签规则；checkout 需用 v4 并确保 github_token 有读写权限；缓存应基于 lockfile 哈希动态生成 key。
GitHub Actions 配置文件放哪？不放对位置 CI 直接不触发
GitHub Actions 只认 .github/workflows/ 目录下的 YAML 文件，路径错一丁点都不行。常见错误是把 ci.yml 放在项目根目录、.github/ 根下，或者拼错 workflows（比如写成 workflow 或 Workflows）。
正确做法：
- 确保路径为
.github/workflows/ci.yml（大小写敏感，Linux 风格路径） - 文件后缀必须是
.yml或.yaml，推荐统一用.yml - 首次提交后，去 GitHub 仓库的 Actions 标签页手动刷新，别等推送——有时缓存会延迟识别新 workflow
Git 提交触发条件写错，push 事件根本不会跑 CI
默认配置里 on: push 看似简单，但实际常因分支名、路径过滤或标签规则漏掉关键提交。比如你只改了 docs/ 下的文件，但没配 paths，CI 却因 on: push 无条件触发；反过来，如果写了 branches: [main] 却在 dev 分支上提交，CI 就静默跳过。
实用建议：
- 明确指定分支：
on: push: branches: [main, develop]，避免依赖默认行为 - 排除文档或配置变更：
paths-ignore: ['docs/**', '.github/**']，省资源也防误触发 - 需要 tag 发布才构建？加
tags: ['v*']，别让每次git commit都拉镜像
Git 拉取代码失败：checkout action 版本太老或 token 权限不足
很多 CI 报错 fatal: could not read Username for 'https://github.com': No such device or address，本质是 actions/checkout@v2 默认用只读 token，而某些操作（如推送衍生分支、提交生成文件）需要写权限。
解决路径很直接：
- 升级 checkout action 到
v4：uses: actions/checkout@v4（v3/v4 默认启用persist-credentials: false，更安全） - 需要写 Git（比如自动发布版本号），显式传入 token：
with: { token: ${{ secrets.GITHUB_TOKEN }} } - 确认
GITHUB_TOKEN的权限：仓库 Settings → Actions → General → “Workflow permissions” 必须设为 Read and write permissions，否则即使写了 token 也 403
Node.js / Python 环境没缓存，每次重装依赖拖慢 CI
CI 最耗时环节通常是安装依赖。GitHub Actions 自带 actions/cache，但缓存键（key）写错就等于没用。常见坑是用固定字符串当 key，或没包含 lockfile 哈希，导致缓存永远不命中。
高效写法示例（以 Node.js 为例）：
uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
关键点：
-
hashFiles()必须指向真实存在的 lockfile，Python 用poetry.lock或requirements.txt，Rust 用Cargo.lock - 不要用
npm ci却缓存node_modules全局路径（~/.npm更稳），不同 Node 版本间缓存不兼容 - 缓存不是万能的：私有 registry、自定义
.npmrc场景下，需额外restore-keys降级匹配
