自定义 GitHub Actions（JavaScript/Composite Actions）开发 (필요 지식: GitHub Actions 基础, Node.js/JavaScript 基础, YAML 配置能力)

GitHub Actions 基础回顾

开头先问大家一句：你第一次用 GitHub Actions，是不是也有点懵？我记得自己第一次接触的时候，Workflow、Job、Step 一堆新词，脑子里全是问号。别急，咱们先把这些基础知识理顺，后面开发自定义 Action 才不会“踩雷”。

GitHub Actions 到底是什么？一句话总结——它是 GitHub 官方内置的自动化平台，帮你自动完成代码构建、测试、部署等任务。以前很多人用 Jenkins、Travis CI，现在直接在代码库里搞定 CI/CD，效率飞起。比如我维护的一个开源项目，每次 push 到 main 分支，Actions 自动帮我跑测试、打包、部署到阿里云，省心到飞起。

自动化流程怎么组织？最外层是 Workflow（.github/workflows/ 目录下的 YAML 文件），里面可以有多个 Job，每个 Job 又由多个 Step 组成。Job 通常在独立的 Runner 上执行，比如 Ubuntu、Windows、macOS，甚至可以用自托管 Runner。用过腾讯云、阿里云 CI/CD 的朋友，应该对 Runner 这个概念不陌生。

Workflow 什么时候触发？很灵活。最常用的触发事件有 push、pull_request、schedule（定时任务）等。比如我有个 Node.js 项目，每次提交代码或者有 PR 时，Actions 都会自动跑测试，省心又省力。

💡 实用技巧

• 合理利用 Job 并行执行，能大幅缩短整体工作流时间。
• 用 Composite Actions 封装重复步骤，提升可维护性和复用性。
• 选对 Action 类型：JavaScript Action 适合复杂逻辑，Docker Action 保证环境一致，Composite Action 组合简单步骤最方便。

三种主流 Action 类型简介

很多朋友只知道 JavaScript 和 Composite Action，其实还有一个很重要的 Docker Action。我们先来快速过一遍三种类型的区别和适用场景：

1. JavaScript Actions

• 开发语言：Node.js
• 适用场景：需要复杂逻辑、与 GitHub API 交互、处理输入输出参数
• 优点：npm 生态丰富，开发调试方便
• 缺点：依赖管理需要注意（后面会详细讲）

2. Composite Actions

• 开发方式：YAML 组合多个 shell 命令和其他 Action
• 适用场景：封装重复步骤、团队流程标准化
• 优点：无需写代码，易于维护和复用
• 缺点：逻辑复杂时不如 JS 灵活，调试不太友好

3. Docker Actions

• 开发方式：自定义 Dockerfile，容器内运行
• 适用场景：需要特殊依赖、系统工具、跨平台环境一致性
• 优点：环境可控，支持任意语言和工具
• 缺点：构建和拉取镜像速度慢，调试门槛略高

举个例子

有一次我需要用 Python 跑数据分析、再用 Node.js 构建前端，直接用 Composite Action 串起来，省事不少。但如果要用某些只有 Linux 下才有的系统工具，或者需要 Python 3.11 + Node.js 20 的组合环境，Docker Action 就是救命稻草。

JavaScript Actions 开发流程与实战

说到 JavaScript Actions，刚上手的时候我也一脸懵。Node.js 环境、输入输出、依赖怎么管、action.yml 怎么写？别急，下面我用一个完整的开发流程和代码示例，带你一步步搞定。

1. 目录结构

建议新建一个专门的目录，比如 .github/actions/string-uppercase/，结构如下：

2. 编写入口脚本（index.js）

3. 配置 action.yml

注意：main 指向的是打包后的文件（推荐用 ncc 打包，见下文）。

4. 依赖管理和打包

小坑提醒：GitHub Actions 不会自动帮你装依赖！有两种做法：

1. 直接提交 node_modules（适合简单 Action，但不推荐）
2. 用 ncc 打包成单文件（推荐，官方最佳实践）

然后把 dist/index.js 配到 action.yml 里。

5. 本地测试

可以用 act 工具在本地跑 workflow，调试效率高很多。第一次用的时候我还以为只能在线调试，结果 act 一下子省了我一堆时间。

6. 发布到 Marketplace

1. 仓库根目录有 action.yml
2. 打 tag，比如 v1.0.0：
   git tag v1.0.0 && git push origin v1.0.0
3. 打开 Releases，点“发布”
4. 填写 Marketplace 信息，搞定！

经验教训：第一次发布别追求完美，能跑通就行，后续慢慢完善说明和文档。

7. 调用方式

💡 实用技巧

• package.json 里声明所有依赖，并提交 package-lock.json，避免版本不一致。
• 用 core.getInput 和 core.setOutput 处理参数，别直接操作 process.env。
• 发布前充分测试，善用 core.debug 打印日志。
• 遇到“Action 不输出”时，先检查 setOutput 是否写对。

Composite Actions 设计与实用案例

Composite Actions 是什么？说白了，就是用 YAML 把一堆 shell 命令和其他 Action 拼成一个整体，像搭积木一样。刚开始我也觉得“这玩意有啥用”，结果项目一大，发现它真是省心神器。

1. 典型结构

小坑提醒：输出变量要用 $GITHUB_OUTPUT，直接 echo 没用！

2. 调用方式

3. 适用场景

• 团队统一流程（如代码检查、单元测试）
• 多项目复用，减少 copy paste
• 复杂工作流拆分成小块，方便维护

经验分享：别贪多，一次封装一个小流程，后面维护才不会炸锅。输入输出参数写清楚，团队协作更顺畅。

💡 实用技巧

• 输入参数尽量设置默认值，减少调用时配置负担。
• 用 id 标识步骤，方便后续通过 ${{ steps.<id>.outputs }} 访问结果。
• 结合 continue-on-error 和输出变量，让 Composite Action 反馈执行状态而不中断整个 workflow。

Docker Actions 简介与典型场景

Docker Actions 其实是 GitHub Actions 的“终极形态”。它允许你用 Dockerfile 自定义运行环境，支持任意语言和工具，环境一致性拉满。

1. 什么时候用 Docker Action？

• 需要用到系统级依赖（比如某些 C/C++ 工具、特殊版本的 Python、Go、Java）
• 需要跨平台环境一致性
• 你的 Action 不方便用 Node.js 或 shell 实现

2. 开发流程简述

1. 新建目录，写 Dockerfile
2. 编写入口脚本（如 entrypoint.sh、app.py 等）
3. 配置 action.yml，指定 runs.using: docker 和 image: Dockerfile
4. 构建和测试

简单示例

注意事项：

• Docker Action 只能在 Linux Runner 上运行
• 镜像构建和拉取速度较慢，建议合理缓存依赖
• 适合有特殊依赖或环境要求的场景

我的翻车经历：有一次用 Docker Action，结果忘了加 chmod +x entrypoint.sh，导致 Action 死活跑不起来，调试了半天才发现是权限问题。大家一定要注意！

自定义 Actions 的实际应用案例

说到实战，刚开始我也只会用 Marketplace 上的现成 Action。后来项目一复杂，发现自己写 Action 真的能省下不少时间。下面给大家分享几个真实案例：

1. 自动化构建与测试

workflow 里这样用：

2. 复杂部署流程分块管理

3. 代码质量检查

安全提醒：敏感信息一定要放在 Secrets 里，别写在代码里！我有次直接写明文 token，结果被安全机器人警告，差点社死……

4. 多环境多版本测试（Matrix 策略）

经验总结：用 matrix + secrets + 环境变量，可以灵活配置不同环境的部署密钥、通知 webhook，自动化能力直接拉满！

常见坑点与解决方案大盘点

开发自定义 Actions，难免会遇到各种“翻车现场”。下面我把自己踩过的坑和解决办法都列出来，大家别再重复我的错误！

1. Node.js 版本兼容性

本地用 Node.js 18，Actions Runner 却是 16 或 20，结果一堆语法报错。解决办法：

action.yml 里也要写对 runs.using: node20。

2. Composite Actions 调试难

Composite Action 调试不如 JS Action 方便，日志还模糊。我的做法是每一步都加 echo "到这儿了"，或者用 core.debug 打印变量，逐步排查。

3. YAML 语法错误

缩进、冒号、变量引用错了，Action 直接挂掉。建议用 yamllint 检查，出错时点开日志看具体哪一行。

4. Secrets 和环境变量安全

敏感信息一定要放在 Secrets，workflow 里用 ${{ secrets.MY_TOKEN }} 调用。调试敏感变量时，只显示前几位，别全量输出：

5. 依赖管理

JS Action 别忘了用 ncc 打包，或者提交 node_modules。否则别人 clone 下来啥都跑不起来。

6. Docker Action 权限问题

entrypoint.sh 别忘了加执行权限，不然 Action 会直接报错。

安全性与维护性最佳实践

自动化虽好，安全和可维护性也不能忽视。下面这些经验，都是我“用血换来的”：

1. 管理 Secrets

• 所有敏感信息（API Token、Webhook、私钥等）都放在 GitHub Secrets
• 不要在日志或代码里输出 secrets
• 定期轮换和清理不再使用的 secrets

2. 版本控制

• 发布 Action 时用语义化 tag（v1、v1.0.0），workflow 里引用固定 tag，避免因主分支变动导致不可预期的行为
• 对 Composite/JS Action 都建议加 changelog，方便团队协作和回溯

3. 权限最小化

• workflow 权限（permissions）只开需要的，比如只读代码、只写 PR 评论等
• Docker Action 只暴露必要端口和命令，减少攻击面

4. 自动化测试和持续集成

• 给自定义 Action 写自动化测试（可以用 act 本地跑）
• 发布前用不同输入参数和异常情况多测几遍

5. 文档和维护

• 每个 Action 都写清楚输入输出、使用方式和注意事项
• Composite Action 推荐用注释说明每一步的作用

结论与进阶建议

回头看看，我们已经把自定义 GitHub Actions 的基础原理、三种主流类型、开发流程、实用案例、常见坑点和安全维护全都聊了一遍。是不是感觉自动化其实也没那么神秘？只要动手实践，踩踩坑，很快就能玩转。

下一步，建议你选一个实际项目，试着开发并集成自己的 GitHub Action，比如自动构建发布文档、定制代码检查，或者团队专属的自动化流程。别怕出错，出错了就改，慢慢你也能成为团队里的“自动化大神”！

如果你有更多疑问或者想交流经验，欢迎留言，我们一起进步。毕竟，自动化的路上，大家都是“摸着石头过河”，多分享多成长！

📚 参考资料和进阶学习

官方文档

• GitHub Actions - 创建 JavaScript 操作
• GitHub Actions - 复合操作（Composite Actions）
• GitHub Actions - Docker Actions
• GitHub Actions - 工作流程语法参考
• Node.js 官方文档

教程

• 📄 GitHub Actions 入门教程（JavaScript 自定义 Action）
• 🎥 Creating GitHub Actions with JavaScript
• 📄 GitHub Actions Composite Actions Tutorial
• 📄 GitHub Actions 深入解析与实战

实用工具

• 🔧 act - 本地运行和调试 GitHub Actions 工作流
• 🔧 Visual Studio Code - 编写和调试 JavaScript 及 YAML 文件的集成开发环境
• 🔧 ESLint - JavaScript 代码质量和规范检查工具

社区

• 🐙 GitHub Actions Discussions
• 💬 GitHub Actions Community
• 🟠 r/github_actions

🔗 相关主题

• GitHub Actions 高级用法与调试技巧
  深入理解事件、上下文、Secrets、环境变量等高级配置，提升 Action 的稳定性与可维护性。

• JavaScript/Node.js 在自动化脚本中的应用
  掌握如何用 JavaScript/Node.js 编写高效、可复用的自动化脚本，是开发 JavaScript Action 的基础。

• YAML 配置最佳实践
  学习 YAML 语法、结构化表达和常见陷阱，提升 workflow 配置的可读性与可维护性。

📈 下一步

1. 编写自己的 JavaScript Action 并发布到 GitHub Marketplace
2. 将常用步骤封装为 Composite Action 并应用到多个项目
3. 为自定义 Action 编写自动化测试和持续集成流程
4. 探索与第三方 API 或云服务的集成

写到这里，感觉自己又复盘了一遍“踩坑史”。自动化的路上，难免会遇到各种奇葩问题，但只要你愿意多试、多问、多总结，迟早能把这些“黑科技”玩得溜溜的。你有没有什么有趣的自动化故事？欢迎留言，我们一起吐槽，一起成长！