自定义 GitHub Actions(JavaScript/Composite Actions)开发 (필요 지식: GitHub Actions 基础, Node.js/JavaScript 基础, YAML 配置能力)
深入解析自定义 GitHub Actions(JavaScript/Composite Actions)开发,帮你打造灵活高效的自动化工作流,提升团队协作和代码复用能力。
哎,咱们又见面啦!上次那篇《掌握使用GitHub Actions实现文档自动化生成和发布》大家看得还顺利吗?评论区好多朋友都在问:“能不能多讲讲自定义 GitHub Actions(JavaScript/Composite Actions)开发?”好,这次我们就把这个话题掰开揉碎,聊个透!
你是不是也有过这种感觉:GitHub Marketplace 里的现成 Actions 总是差点意思,想要的功能总有点“差一口气”?我自己刚用 Actions 的时候,觉得官方的东西已经很强了,结果项目一复杂,才发现——自定义 Action 才是打开自动化新世界大门的钥匙。说真的,踩过不少坑,走了不少弯路,甚至有一次为了搞定一个自定义 Action,愣是折腾了三小时,最后才发现是 action.yml 写错了名字……是不是很真实?
为什么要聊这个?因为自定义 Actions 不只是让 CI/CD 更灵活,还能让团队协作和代码复用率直接起飞。项目越大、自动化需求越多,自己动手开发 JavaScript Action、Composite Action,甚至 Docker Action,绝对是让你的工作流“如虎添翼”的秘密武器!
今天我们会一起拆解这些内容:
- 什么是自定义 GitHub Actions? JavaScript、Composite、Docker 三种主流类型的区别和适用场景
- 如何从零开发自己的 Action,并在项目中复用
- 实操开发流程和完整代码示例,让你一看就能上手
- 常见坑点和我的翻车经历(放心,走过的弯路都给你标出来)
- 安全性和维护性最佳实践,比如 secrets 管理和版本控制
无论你是想为团队打造专属 Workflow 工具,还是想让自动化脚本更优雅可控,这篇文章都能帮你迈出关键一步。别担心,不需要完美起步,哪怕出点小 bug 也没关系,重要的是一起成长。准备好了吗?那我们就正式开启自定义 Actions 的探索之旅吧!
目录
- GitHub Actions 基础回顾
- 三种主流 Action 类型简介(JavaScript/Composite/Docker)
- JavaScript Actions 开发流程与实战
- Composite Actions 设计与实用案例
- Docker Actions 简介与典型场景
- 自定义 Actions 的实际应用案例
- 常见坑点与解决方案大盘点
- 安全性与维护性最佳实践
- 结论与进阶建议
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/,结构如下:
.github/
actions/
string-uppercase/
action.yml
index.js
package.json
package-lock.json
2. 编写入口脚本(index.js)
const core = require('@actions/core');
try {
// 获取输入参数
const inputStr = core.getInput('input');
// 处理逻辑
const outputStr = inputStr.toUpperCase();
// 设置输出
core.setOutput('output', outputStr);
} catch (error) {
core.setFailed(error.message);
}
3. 配置 action.yml
name: "String Uppercase"
description: "将输入字符串转成大写"
inputs:
input:
description: "需要转换的字符串"
required: true
outputs:
output:
description: "转换后的大写字符串"
runs:
using: "node20"
main: "dist/index.js"
注意:main 指向的是打包后的文件(推荐用 ncc 打包,见下文)。
4. 依赖管理和打包
小坑提醒:GitHub Actions 不会自动帮你装依赖!有两种做法:
- 直接提交 node_modules(适合简单 Action,但不推荐)
- 用 ncc 打包成单文件(推荐,官方最佳实践)
npx @vercel/ncc build index.js -o dist
然后把 dist/index.js 配到 action.yml 里。
5. 本地测试
可以用 act 工具在本地跑 workflow,调试效率高很多。第一次用的时候我还以为只能在线调试,结果 act 一下子省了我一堆时间。
6. 发布到 Marketplace
- 仓库根目录有 action.yml
- 打 tag,比如 v1.0.0:
git tag v1.0.0 && git push origin v1.0.0 - 打开 Releases,点“发布”
- 填写 Marketplace 信息,搞定!
经验教训:第一次发布别追求完美,能跑通就行,后续慢慢完善说明和文档。
7. 调用方式
- name: 字符串大写转换
uses: your-org/string-uppercase-action@v1
with:
input: "hello world"
💡 实用技巧
- package.json 里声明所有依赖,并提交 package-lock.json,避免版本不一致。
- 用 core.getInput 和 core.setOutput 处理参数,别直接操作 process.env。
- 发布前充分测试,善用 core.debug 打印日志。
- 遇到“Action 不输出”时,先检查 setOutput 是否写对。
Composite Actions 设计与实用案例
Composite Actions 是什么?说白了,就是用 YAML 把一堆 shell 命令和其他 Action 拼成一个整体,像搭积木一样。刚开始我也觉得“这玩意有啥用”,结果项目一大,发现它真是省心神器。
1. 典型结构
name: 'Lint & Format'
description: 'Run ESLint and Prettier, return formatted result'
inputs:
node-version:
description: 'Node.js 版本'
required: false
default: '16'
outputs:
lint-result:
description: 'Lint 执行结果'
runs:
using: 'composite'
steps:
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: ${{ inputs['node-version'] }}
- name: Run ESLint
run: |
npx eslint . > lint.log
echo "result=$(cat lint.log)" >> $GITHUB_OUTPUT
- name: Run Prettier
run: npx prettier --check .
- name: Set output
run: echo "lint-result=$(cat lint.log)" >> $GITHUB_OUTPUT
小坑提醒:输出变量要用 $GITHUB_OUTPUT,直接 echo 没用!
2. 调用方式
jobs:
lint-job:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: your-org/lint-format-action@v1
id: lint
with:
node-version: '18'
- run: echo "结果:${{ steps.lint.outputs.lint-result }}"
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. 开发流程简述
- 新建目录,写 Dockerfile
- 编写入口脚本(如 entrypoint.sh、app.py 等)
- 配置 action.yml,指定
runs.using: docker和image: Dockerfile - 构建和测试
简单示例
name: "My Docker Action"
description: "在容器中运行的自定义 Action"
runs:
using: "docker"
image: "Dockerfile"
args:
- ${{ inputs.input }}
inputs:
input:
description: "输入参数"
required: true
注意事项:
- Docker Action 只能在 Linux Runner 上运行
- 镜像构建和拉取速度较慢,建议合理缓存依赖
- 适合有特殊依赖或环境要求的场景
我的翻车经历:有一次用 Docker Action,结果忘了加 chmod +x entrypoint.sh,导致 Action 死活跑不起来,调试了半天才发现是权限问题。大家一定要注意!
自定义 Actions 的实际应用案例
说到实战,刚开始我也只会用 Marketplace 上的现成 Action。后来项目一复杂,发现自己写 Action 真的能省下不少时间。下面给大家分享几个真实案例:
1. 自动化构建与测试
// .github/actions/run-tests/index.js
const { execSync } = require('child_process');
try {
execSync('npm install', { stdio: 'inherit' });
execSync('npm test', { stdio: 'inherit' });
console.log('✅ 测试通过');
} catch (e) {
console.error('❌ 测试失败');
process.exit(1);
}
workflow 里这样用:
- name: 运行单元测试
uses: ./.github/actions/run-tests
2. 复杂部署流程分块管理
# .github/actions/deploy/action.yml
name: '部署流程'
runs:
using: "composite"
steps:
- name: 安装依赖
run: npm install
- name: 部署到服务器
run: npm run deploy
- name: 通知钉钉
run: curl -X POST ${{ secrets.DINGTALK_WEBHOOK }} -d '{"msgtype": "text", "text": {"content": "部署完成"}}'
3. 代码质量检查
- name: 代码规范检查
run: npm run lint
- name: 安全扫描
run: npx sonarqube-scanner
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
安全提醒:敏感信息一定要放在 Secrets 里,别写在代码里!我有次直接写明文 token,结果被安全机器人警告,差点社死……
4. 多环境多版本测试(Matrix 策略)
strategy:
matrix:
node: [14, 16, 18]
db: [mysql, postgres]
steps:
- name: 设置 Node.js
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node }}
- name: 测试数据库 ${{ matrix.db }}
run: npm test -- --db=${{ matrix.db }}
经验总结:用 matrix + secrets + 环境变量,可以灵活配置不同环境的部署密钥、通知 webhook,自动化能力直接拉满!
常见坑点与解决方案大盘点
开发自定义 Actions,难免会遇到各种“翻车现场”。下面我把自己踩过的坑和解决办法都列出来,大家别再重复我的错误!
1. Node.js 版本兼容性
本地用 Node.js 18,Actions Runner 却是 16 或 20,结果一堆语法报错。解决办法:
- uses: actions/setup-node@v4
with:
node-version: '18'
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 }} 调用。调试敏感变量时,只显示前几位,别全量输出:
echo "Token prefix: ${MY_TOKEN:0:4}***"
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 高级用法与调试技巧
深入理解事件、上下文、Secrets、环境变量等高级配置,提升 Action 的稳定性与可维护性。 -
JavaScript/Node.js 在自动化脚本中的应用
掌握如何用 JavaScript/Node.js 编写高效、可复用的自动化脚本,是开发 JavaScript Action 的基础。 -
YAML 配置最佳实践
学习 YAML 语法、结构化表达和常见陷阱,提升 workflow 配置的可读性与可维护性。
📈 下一步
- 编写自己的 JavaScript Action 并发布到 GitHub Marketplace
- 将常用步骤封装为 Composite Action 并应用到多个项目
- 为自定义 Action 编写自动化测试和持续集成流程
- 探索与第三方 API 或云服务的集成
写到这里,感觉自己又复盘了一遍“踩坑史”。自动化的路上,难免会遇到各种奇葩问题,但只要你愿意多试、多问、多总结,迟早能把这些“黑科技”玩得溜溜的。你有没有什么有趣的自动化故事?欢迎留言,我们一起吐槽,一起成长!