GitHub Actions工作流配置，避坑必备

▌ 技术引导
GitHub Actions工作流配置是自动化构建和部署的核心，但如果你没有踩过坑，那你一定没真的搞明白它的工作原理。我见过太多人因为配置错误导致流程永远卡在某个阶段，比如没有正确设置环境变量，或者在容器镜像中遗漏了关键依赖。有些人用默认的runner，结果执行速度慢得离谱，这时候得考虑自定义runner或者切换到Linux环境。真实场景里，大家总是在setup_path和setup_node这些命令里翻车，要确保绝对路径正确，否则连基础依赖都装不上。还有人被token权限限制搞崩溃，权限不匹配的话，部署到私有仓库会直接报错。如果你在流水线中用到了docker或者k8s，那必须明确指定构建上下文和挂载卷，不然容器根本无法访问本地文件。这些细节都直接关系到构建是否稳定，所以千万别省略。

▌ 技术参考

一
GitHub Actions的配置不是简单的YAML文件，它是一种流程驱动的工具，每个步骤都依赖于特定的runner环境。如果项目里包含Node.js依赖，通常会用setup_node和npm install这俩命令，但很多人忽略了指定node_version参数，导致版本不一致。比如在actions/setup-node@latest这个action里，必须加上with: { node-version: '18.x' }，否则会用默认版本，可能带来兼容性问题。如果你用的是私有仓库，必须确保在workflow中配置了正确的GITHUB_TOKEN，并且权限要足够，否则无法拉取代码或推送结果。这个token可以在Settings > Secrets里生成，记得不要用public token，它只适用于公共仓库。

二
在配置工作流时，很多人习惯直接复制别人的配置，结果发现自己的项目结构不同，导致路径错误。例如，如果项目在子目录下，必须在jobs的steps里加上working-directory: ./your-project-folder，否则命令会在根目录执行，找不到文件。像npm install这种命令如果在错误的目录里运行，会直接报错。此外，环境变量的设置要精准，比如在env部分定义变量时，不要遗漏了前缀，例如GITHUB_API_TOKEN这样的变量，如果没加前缀，会被下游命令误读。真实案例中，有些团队在部署前会忘记设置CI_ENV=production，导致测试环境和生产环境混合，引发问题。

三
GitHub Actions的runner分为hosted和self-hosted两种。hosted runner是官方提供的，但它的性能有限，尤其在处理大量文件或复杂依赖时。比如如果你用的是Python项目，且需要安装大量第三方库，hosted runner可能会超时。这时候可以考虑使用自定义runner，但需要配置SSH密钥和Docker环境，否则无法连接。在自定义runner上，必须确保Docker版本与项目需求一致，否则构建失败。更极端的场景里，有些项目需要GPU加速，这时候必须用hosted runner的特定类型，如ubuntu-latest或windows-latest，或者自己搭建带GPU的runner，这会增加很多额外配置。

四
配置工作流时，要深知run的策略。比如在run步骤中，如果执行时间较长，必须加上timeout-minutes参数，否则流程会因为超时而终止。具体配置是：runs-on: ubuntu-latest，然后在某个步骤里写timeout-minutes: 30。这在处理大体积数据或复杂编译任务时非常关键。另外，如果你使用了docker，必须在容器中挂载工作目录，例如在steps里加上uses: docker://some-image，然后设置working-directory。如果容器和宿主机之间的路径没对齐，就会出现找不到文件的错误。有些项目会用buildx来构建镜像，这时候要配置正确的构建上下文，避免镜像构建失败。

五
在配置中，很多时候会遇到权限问题。例如，当你在某个步骤中需要写入文件到特定目录，必须确保该步骤的runner有写权限。这时候可以在steps中加入permissions配置，比如permissions: { 'path/to/dir': 'write' }，否则会报错。更常见的问题是路径错误，比如使用相对路径时，容易导致命令无法找到文件，这时候要使用绝对路径或者在steps里指定working-directory。另外，一些环境变量需要显式声明，比如在env部分设置CI=true，否则某些脚本可能无法识别环境，导致错误。

六
当配置了多个jobs时，要清楚它们之间的依赖关系。比如使用jobs的needs属性，这在需要顺序执行时非常有用。比如如果有一个job负责测试，另一个负责部署，那么部署job必须需要测试job成功。配置时要注意needs的顺序和条件，否则可能导致部署job在测试未完成时就开始执行，带来不可预测的问题。另外，有些项目会使用matrix策略，比如同时在linux和windows上运行测试，这时候需要在jobs里配置matrix: node-version，然后指定不同的runs-on值，确保测试覆盖全面。

七
在实际操作中，很多人会因为缓存配置错误而反复失败。比如在缓存步骤中，使用setup-cache这个action时，必须确保缓存的key和路径正确。如果缓存路径设置不正确，比如写成了./node_modules，而实际项目结构不同，就会导致缓存失效，重新下载，浪费时间。这时候要检查缓存key是否包含版本信息，比如使用$ { { hashFiles('package-lock.json') }}，这样每次依赖变化都会触发重新缓存。另外，有些人会发现缓存没有命中，其实是因为没有正确设置cache-key，或者缓存文件没有被包含在缓存路径中，导致每次都是全量下载。

八
在处理敏感信息时，必须严格使用secrets。比如在部署阶段，需要使用SSH密钥连接到远程服务器，这时候必须在secret里添加SSH_PRIVATE_KEY，并在steps中通过with: { env: { SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} } }来注入。如果不使用secrets，直接写在YAML里，会被暴露在日志中，带来安全风险。有些团队会用SSH keys来配置runner的权限，这时候必须确保存储在secret里的key是正确的格式，否则连接会失败。此外，有些项目会用github.com的token来触发webhook，这时候也要在secret里设置GITHUB_TOKEN，并确保它有正确的权限。

九
GitHub Actions的event触发机制是关键，但很多人忽略了event的细节。比如当使用push event时，会触发所有分支的构建，而有些项目只希望在特定分支上运行，这时候需要配置ref: 'refs/heads/main'，否则会构建到其他分支。更复杂的场景里，有些团队会用workflow_dispatch来手动触发流程，这时候需要在YAML里配置name: Run Manually，并且在界面里手动点击。如果只配置了push和pull_request，但没有设置合适的ref过滤，就会出现流程在不该执行的时候运行，浪费资源。所以要根据项目需求，精确配置events。

十
在处理多语言项目时，必须确保每个步骤的工具链正确。比如在同一个工作流里同时使用node.js和Python，需要分别调用setup-node和setup-python，否则可能会出现环境冲突。比如使用setup-node@latest和setup-python@latest，然后分别指定版本号。如果某些步骤需要切换环境，比如在测试后清理缓存，这时候要确保清理命令不会误删其他步骤需要的文件。真实案例中，有团队在清理步骤里执行rm -rf ，结果删除了所有依赖，导致后续步骤失败。这时候要使用更安全的清理方式，比如只删除特定目录。

十一
当使用docker时，必须配置正确的buildx参数。比如在构建镜像时，写入docker build命令的参数要仔细检查，比如--build-arg和--label这些选项是否被正确传递。如果在dockerfile中使用了ARG，必须在构建时通过build-args指定，否则会报错。比如在steps里写buildx build --build-arg VERSION=1.0.0 -t your-image:latest .，这样会把版本参数传入dockerfile。如果没传，那ARG的值会是默认，可能带来版本混乱。而且docker run的命令也要确保正确，比如指定了--network none，或者挂载了正确的卷。

十二
当用到缓存时，必须注意缓存的粒度和有效性。比如如果只缓存npm依赖，而你的项目同时依赖yarn，就必须指定正确的缓存路径。有时候会配置错误的文件，比如把node_modules直接缓存，结果在后续步骤中发现某些依赖版本不一致，这时候需要重新构建。正确做法是使用setup-cache的key参数，比如key: 'node_modules-v1'，然后在dockerfile或构建过程中确保所有依赖都统一版本。此外，某些项目需要在缓存中保留编译产物，这时候要配置正确的路径，避免缓存失效。

十三
在配置依赖安装步骤时，必须考虑是否使用缓存。例如，对于npm install，尽量使用npm ci来确保依赖版本一致，而不要用npm install。这样能避免版本冲突，尤其是当package-lock.json存在时。如果想使用缓存，可以在steps中加入setup-cache，然后指定缓存路径和key。如果项目用的是yarn，同样需要配置yarn install，而且要确保yarn版本正确，否则会报错。有些项目会用yarn set version 1.22.19来固定版本，防止不同runner之间的版本差异。

十四
当使用GitHub Actions的矩阵构建时，必须确保每个config的环境都能正常运行。比如matrix的node-version配置里，如果有一个版本无法通过，会直接导致整个矩阵失败。这时候要检查各个版本的依赖是否兼容，比如某些npm包可能在node 18下无法使用，这时候需要调整matrix配置，或者在每个环境里加条件判断。比如使用if: matrix.node-version == '18.x'，这样能确保只有特定版本的环境才会执行特定步骤。此外，有些项目会用matrix.os来同时构建Linux和Windows，这时候要确保测试脚本兼容两种系统。

十五
处理错误时，必须配置详细的日志输出。例如，在每个步骤的run命令中，使用echo来输出关键信息，这样能更快定位问题。如果某个步骤失败，可以使用continue-on-error: true来允许流程继续，但要确保后续步骤能正常运行。比如在安装依赖时，如果失败，可以设置continue-on-error: true，然后在后续步骤里验证安装结果。此外，有些项目会用script的输出来触发后续动作，比如使用exit code来判断是否继续执行。如果某个脚本返回非零值，可以配置if: ${{ success }}，这样能控制流程走向。

十六
在使用环境变量时，必须确保它们被正确注入。例如，某些脚本需要访问特定的环境变量，比如API密钥或数据库连接字符串。如果没在env里正确配置，就会导致脚本无法运行。比如在YAML里写env: { DB_URL: 'localhost:3306' }，然后在脚本里使用$DB_URL来访问，这样就能确保变量可用。但有些脚本会使用shell变量，比如$DB_URL，这时候要确保它在上下文中被正确设置。如果没设置，就会报错。有些团队会用secrets来存储敏感变量，这时候要确保在steps里正确引用。

十七
在配置CI/CD流程时，必须考虑分支策略。比如有些项目只在main分支上部署，这时候需要在jobs的if条件里加ref: 'refs/heads/main'，确保只有主分支才会触发部署。有些团队会用pull_request的sha来触发测试，这时候需要配置特定的event和ref，避免误触发。如果项目使用了git hooks，必须在GitHub Actions里配置对应的触发条件，否则流程不会自动执行。有些情况下，配置了push和pull_request，但没有设置正确的ref，就会导致流程误执行。

十八
在配置GitHub Actions时，必须注意runner的环境。比如使用hosted runner时，可能需要安装额外的工具，这时候要在steps里加入setup命令。比如使用setup-python@latest来安装Python环境，否则后续脚本无法运行。有些项目需要特定的环境变量，比如在构建过程中需要设置CFLAGS或者LDFLAGS，这时候必须在env里配置。如果这些变量没被设置，会导致编译失败。有些团队会用环境变量来控制构建类型，比如CI=true，这样能避免某些不必要的步骤。

十九
在使用GitHub Actions的自定义runner时，必须确保网络配置正确。比如有些自定义runner在内网中，无法访问GitHub的API，这时候需要配置代理。配置方法是在runner的初始化脚本中添加环境变量，比如HTTP_PROXY和HTTPS_PROXY，或者在YAML里配置run的environment。如果没配置，会导致流程无法获取token，或者无法访问依赖包。有些团队会用SSH隧道来连接内网，这时候需要在runner上配置正确的SSH密钥和端口，否则无法建立连接。

二十
在配置GitHub Actions的缓存和部署时，必须确保缓存的版本控制。比如在构建过程中，每次修改了package-lock.json，缓存就会失效，这时候需要在缓存key里加入文件内容的哈希值。比如key: 'npm-cache-${{ hashFiles('package-lock.json') }}'，这样能确保缓存只在依赖变化时重新下载。有些团队会用docker镜像作为缓存，这时候需要在构建时使用docker buildx build，并且确保镜像标签正确。如果镜像标签不变，但内部结构变了，导致缓存无效，就会浪费大量时间。