@actions/core 版本演进全解析：从 1.0 到 3.0 的核心 API 变迁与实战指南

CI/CD开发工具【免费下载链接】toolkitThe GitHub ToolKit for developing GitHub Actions.项目地址https://gitcode.com/gh_mirrors/to/toolkit点击查看免费下载导读actions/core是 GitHub Actions Toolkit 中面向 Action 开发者的核心库负责 Action 的输入输出读写、日志与注解、密钥掩码、环境变量导出、Job Summary 与 OIDC Token 获取等基础能力。本文以仓库内 packages/core/RELEASES.md 的版本记录为主线结合 packages/core/README.md 的使用说明与 packages/core/src/core.ts 等源码实现梳理从 1.0.0 到 3.0.1 的 API 变迁脉络并给出可直接落地的调用示例与迁移要点。读完本文你将掌握 actions/core 每个关键版本引入的能力、底层命令协议的工作原理以及升级到 ESM-only 3.x 时的正确姿势。一、版本脉络总览一条清晰的 API 进化时间线截至当前仓库快照actions/core最新版本为3.0.1见 packages/core/package.json 中的version: 3.0.1。其发布历史横跨三个大版本核心变化可归纳为四个阶段阶段版本区间主题1.0.0 – 1.2.x初版与命令协议演进输入输出、日志、group、saveState/getState、setSecret、echo 命令、命令转义修复1.3.0 – 1.9.x能力扩充getBooleanInput、getMultilineInput、notice 注解、OIDC getIDToken、路径工具、环境文件命令1.10.0 – 1.11.1稳定性与平台化saveState/setOutput 改走环境文件、平台信息工具、移除 uuid 依赖2.0.0 – 3.0.x现代化改造Node 24 支持、依赖升级、3.0.0 起 Package 仅支持 ESM其中最关键的两条主线是runner 命令从##前缀迁移到::前缀1.1.1以及从 stdout 命令通道逐步迁移到环境文件GITHUB_ENV / GITHUB_OUTPUT / GITHUB_STATE / GITHUB_PATH通道1.2.6、1.10.0。理解这两条主线就理解了 actions/core 全部 API 的内部通信机制。二、命令协议##时代与::时代actions/core的一切能力最终都通过向 stdout 写入特定格式的命令字符串与 Actions Runner 通信。1.1.1 版本将命令前缀从##切换为::官方说明称“should have no noticeable impact”即对使用者无感知但为后续命令协议统一铺平了道路。命令格式在源码 packages/core/src/command.ts 中有明确注释::name keyvalue,keyvalue::message例如::warning::This is a warning message—— 输出一条 warning 注解::set-env nameMY_VAR::some value—— 设置环境变量旧协议::add-mask::secretValue123—— 注册日志掩码消息与属性值都会经过转义处理见escapeData/escapeProperty%转义为%25、\r转义为%0D、\n转义为%0A属性值还会额外将:转义为%3A、,转义为%2C。1.2.2 版本的“Fix escaping for runner commands”正是围绕这套转义规则做的修复对应测试用例可见 packages/core/tests/core.test.ts 对setFailed消息中转义结果的断言。1.2.4 版本还放宽了对非字符串命令输入的限制toCommandValue见 packages/core/src/utils.ts对null/undefined返回空字符串对字符串原样返回其余类型布尔、数字、对象统一走JSON.stringify这也解释了为何测试中core.setOutput(some output, false)会输出::set-output namesome output::false。三、环境文件File Command时代exportVariable / addPath / setOutput / saveState3.1 迁移背景1.2.6 版本将exportVariable与addPath改为优先使用环境文件1.10.0 又让saveState与setOutput在可用时同样走环境文件通道1.9.1 为exportVariable引入随机化分隔符防止注入攻击。所谓“环境文件”是指 Runner 通过GITHUB_ENV、GITHUB_OUTPUT、GITHUB_STATE、GITHUB_PATH这四个环境变量指明的磁盘文件。源码中的判定逻辑非常清晰packages/core/src/core.tsexport function exportVariable(name: string, val: any): void { const convertedVal toCommandValue(val) process.env[name] convertedVal const filePath process.env[GITHUB_ENV] || if (filePath) { return issueFileCommand(ENV, prepareKeyValueMessage(name, val)) } issueCommand(set-env, {name}, convertedVal) }即只要检测到对应的环境文件路径就写入文件否则回退到 stdout 命令通道set-env/add-path/set-output/save-state。setOutputcore.ts与saveStatecore.ts的实现模式完全一致。3.2 随机分隔符机制文件命令写入的内容由prepareKeyValueMessage生成见 packages/core/src/file-command.tskeyghadelimiter_uuid value ghadelimiter_uuid其中分隔符ghadelimiter_${crypto.randomUUID()}每次调用随机生成1.9.1 版本“Randomize delimiter”的含义所在且源码会校验 key 与 value 均不得包含该分隔符否则抛出异常。测试中通过 mockcrypto.randomUUID固定为9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d来断言写入格式见 core.test.ts。3.3 使用示例// 导出环境变量供本步骤及后续步骤使用 core.exportVariable(envVar, Val) // 将工具目录前置到 PATH core.addPath(/path/to/mytool) // 设置输出供下游 action 映射为输入 core.setOutput(outputKey, outputVal) // 保存状态供本 action 的 post 入口读取 core.saveState(pidToKill, 12345)注意由于每个 step 运行在独立进程中跨步骤共享数据只能依赖exportVariable与setOutput这类机制这是 packages/core/README.md 中强调的设计前提。四、输入读取能力的演进getInput 家族4.1 getInput 与 trimWhitespace1.3.0getInput从INPUT_NAME环境变量读取输入名称中的空格会被替换为下划线并转为大写见 core.ts例如my input对应环境变量INPUT_MY_INPUT因此读取是大小写不敏感的——测试getInput(My InPuT)也能命中INPUT_MY_INPUTcore.test.ts。1.3.0 引入了trimWhitespace选项默认true同时要求非必填输入应在action.yml中声明默认值interface InputOptions { /** Optional. Whether the input is required. If required and not present, will throw. Defaults to false */ required?: boolean /** Optional. Whether leading/trailing whitespace will be trimmed for the input. Defaults to true */ trimWhitespace?: boolean } const myInput core.getInput(inputName, { required: true }) const noTrim core.getInput(rawInput, { trimWhitespace: false })4.2 getBooleanInput严格遵循 YAML 1.2 核心模式1.3.0getBooleanInput只接受 YAML 1.2 Core Schema 规定的六种写法true | True | TRUE | false | False | FALSE其余值直接抛出TypeErrorcore.ts错误信息中会给出支持列表。测试对六种写法逐一断言并验证wrong会抛错core.test.ts。const myBooleanInput core.getBooleanInput(booleanInputName, { required: true })4.3 getMultilineInput多行输入按行拆分1.4.01.4.0 新增getMultilineInput先取原始输入按\n拆分成数组并过滤空行默认对每行做 trim1.10.0 明确“trims whitespace by default”trimWhitespace: false时保留原样core.ts。const myMultilineInput core.getMultilineInput(multilineInputName, { required: true })测试验证了默认 trim 行为 val1 \n val2 \n 会得到[val1, val2]而不 trim 时会保留[ val1 , val2 , ]core.test.ts。五、日志、注解与输出分组5.1 五级日志actions/core提供debug/notice/warning/error/info五类输出。debug默认被隐藏需通过开启 Step Debug Logs设置 secretACTIONS_STEP_DEBUG为true才能看到详细说明见 docs/action-debugging.md同时isDebug()通过检测RUNNER_DEBUG 1判断当前是否处于调试模式core.ts该行为在 1.2.3 版本“IsDebug logging”中引入。const myInput core.getInput(input) try { core.debug(Inside try block) // 仅调试模式可见 if (!myInput) { core.warning(myInput was not set) // 黄色警告 注解 } core.info(Output to the actions build log) core.notice(This is a message that will also emit an annotation) } catch (err) { core.error(Error ${err}, action may still succeed though) }error/warning/notice都接受字符串或Error对象后者会经toString()转换见 core.ts。5.2 注解Annotations与 AnnotationPropertieserror/warning/notice会在 Actions 页面与 Pull Request 上生成注解。1.5.0 新增 notice 注解及更多注解字段1.6.0 又为AnnotationProperties增加了file参数使注解可以精确关联到源码文件的某一行某一列export interface AnnotationProperties { /** A title for the annotation. */ title?: string /** The path of the file for which the annotation should be created. */ file?: string /** The start line for the annotation. */ startLine?: number /** The end line for the annotation. Defaults to startLine when startLine is provided. */ endLine?: number /** The start column for the annotation. Cannot be sent when startLine and endLine are different values. */ startColumn?: number /** The end column for the annotation. Defaults to startColumn when startColumn is provided. */ endColumn?: number }这些字段经toCommandProperties映射为命令属性line/endLine/col/endColumn见 utils.ts测试断言了映射关系startLine: 5会变成命令里的line5core.test.ts。注解在 UI 上的呈现效果如下5.3 输出分组1.1.0 引入了group/endgroup。startGroup与endGroup用于手动包裹group则自动包裹一个异步函数并在其结束后确保关闭分组core.tscore.startGroup(Do some function) doSomeFunction() core.endGroup() // 自动包裹异步函数返回函数返回值 const result await core.group(Do something async, async () { const response await doSomeHTTPRequest() return response })六、密钥掩码与命令回显控制6.1 setSecret1.1.3setSecret通过::add-mask::命令将值注册到 Runner此后日志中出现该值的地方都会被替换为***。可保护 API Key、Access Token、认证凭据、带签名的 URL 参数如 SAS Token等敏感信息但注意它只影响后续日志源码注释明确说明此前日志中已出现的值不会被掩盖见 core.ts。core.setSecret(myPassword)测试验证了多行密钥同样会被正确转义后掩码multi\nline\r\nsecret→multi%0Aline%0D%0Asecret见 core.test.ts。1.1.3 还移除了从未实现、也从未生效的exportSecret。6.2 setCommandEcho1.2.41.2.4 新增 Echo 命令setCommandEcho(true/false)输出::echo::on|off控制后续步骤命令是否回显到日志默认关闭除非设置了ACTIONS_STEP_DEBUG见 core.ts。七、Action 状态saveState / getState1.2.0对于带post入口的 Wrapper Action可用状态机制在主执行与清理阶段之间共享数据1.2.0 引入。saveState在可用时写入GITHUB_STATE环境文件getState则读取STATE_NAME环境变量core.ts。action.ymlname: Wrapper action sample inputs: name: default: GitHub runs: using: node12 main: main.js post: cleanup.jsmain.jscore.saveState(pidToKill, 12345)cleanup.jsvar pid core.getState(pidToKill) process.kill(pid)八、OIDC 与 ID TokengetIDToken1.6.01.6.0 新增 OIDC Client 函数getIDToken用于向 GitHub OIDC Provider 请求 JWT ID Token进而换取第三方云厂商的 Access Token。const audience core.getInput(audience, { required: false }) const id_token1 await core.getIDToken() // 默认 audience const id_token2 await core.getIDToken(audience) // 自定义 audience底层实现位于 packages/core/src/oidc-utils.ts通过环境变量ACTIONS_ID_TOKEN_REQUEST_URL与ACTIONS_ID_TOKEN_REQUEST_TOKEN携带的请求地址和 Bearer Token向 Action Service 发起 HTTP 请求默认最多重试 10 次指定 audience 时将其encodeURIComponent后拼接到 URL 的audience参数上。取回的 ID Token 会立即调用setSecret注册掩码避免其被打印到日志。若两个环境变量缺失会分别抛出“Unable to get ACTIONS_ID_TOKEN_REQUEST_TOKEN/URL env variable”的错误。九、路径与平台工具跨系统一致性1.9.0 / 1.11.09.1 路径工具1.9.0toPosixPath将\替换为/toWin32Path将/替换为\toPlatformPath根据运行环境将两类分隔符统一替换为平台对应的path.sep见 packages/core/src/path-utils.ts。三个函数都独立于底层运行系统工作便于在 Action 内统一处理路径toPosixPath(\\foo\\bar) // /foo/bar toWin32Path(/foo/bar) // \foo\bar // Windows runner 上 toPlatformPath(/foo/bar) // \foo\bar // Linux runner 上 toPlatformPath(\\foo\\bar) // /foo/bar对应测试见 packages/core/tests/path-utils.test.ts。9.2 平台信息工具1.11.01.11.0 新增平台信息工具同时移除了对uuid包的依赖改用 Node 原生crypto.randomUUID这正是 1.11.1 修复 Node 18 及更早版本crypto.randomUUID问题的背景。用法packages/core/src/platform.tsimport { platform } from actions/core /* 等价于 os.platform() */ platform.platform // win32 | darwin | linux | ... /* 等价于 os.arch() */ platform.arch // x64 | arm64 | ia32 | ... /* 常用快捷布尔量 */ platform.isWindows // true platform.isMacOS // false platform.isLinux // false /* 获取操作系统名称与版本分别调用 powershell / sw_vers / lsb_release */ const { name, version } await platform.getDetails() // Windows 上nameMicrosoft Windows 11 Enterprise, version10.0.22621注意getDetails()依赖actions/exec调用平台命令powershell、sw_vers、lsb_release仅支持 Windows、macOS、Linux 三类系统。十、Job Summary从 markdownSummary 到 summary1.7.0 / 1.8.01.7.0 引入了markdownSummary扩展1.8.0 将其弃用并推荐使用summary源码中markdownSummary只是summary的别名并标注deprecated见 packages/core/src/summary.ts。summary是一个带缓冲区的单例通过GITHUB_STEP_SUMMARY环境变量定位汇总文件所有内容最终经write()写入磁盘默认追加overwrite: true时覆盖。其文件路径解析与读写权限校验逻辑见 summary.ts。常用 API 一览// 追加原始文本第二个参数控制是否追加 EOL core.summary.addRaw(Some content here :speech_balloon:, true) // 追加操作系统相关的换行符 core.summary.addEOL() // 代码块可指定语法高亮语言 core.summary.addCodeBlock(console.log(hello world), javascript) // 列表ordered 参数控制有序/无序 core.summary.addList([item1, item2, item3], true) // 可折叠 details 元素 core.summary.addDetails(Label, Some detail that will be collapsed) // 图片可指定像素宽高 core.summary.addImage(example.png, alt description of img, { width: 100, height: 100 }) // 标题level 可选默认 h1 core.summary.addHeading(My Heading, 2) core.summary.addSeparator() // hr core.summary.addBreak() // br core.summary.addQuote(To be or not to be, Shakespeare) // blockquote core.summary.addLink(click here, https://github.com) // a 标签 // 表格SummaryTableRow (SummaryTableCell | string)[] const tableData [ { data: Header1, header: true }, { data: MyData1 } ] core.summary.addTable([tableData]) // 缓冲区管理 core.summary.clear() // 清空缓冲区并清空磁盘文件 core.summary.stringify() // 返回缓冲区字符串 core.summary.isEmptyBuffer() // 缓冲区是否为空 core.summary.emptyBuffer() // 仅重置缓冲区 core.summary.write({ overwrite: true }) // 写盘并清空缓冲区十一、面向 3.0 的升级指南ESM-only 迁移3.0.03.0.0 是本包历史上最重要的破坏性变更Package 变为 ESM-onlyCommonJS 消费者必须改用动态import()而非require()。这一声明在 packages/core/package.json 中有三重体现type: module—— 整包按 ESM 解析exports仅暴露import条件import: ./lib/core.js源码全部采用 ESM 语法如import {issue, issueCommand} from ./command.js注意带.js后缀。迁移方式// 旧写法CommonJS3.x 下不再可用 // const core require(actions/core) // 新写法动态 import const core await import(actions/core) // 或在 ESM 模块中直接静态导入 import * as core from actions/core其余版本要点2.0.0 增加对 Node 24 的支持并将actions/http-client升级到 3.x当前 3.0.1 的依赖为actions/exec^3.0.0 与actions/http-client^4.0.0且 2.0.1 曾将actions/exec从 1.1.1 升级至 2.0.0、3.0.1 将undici从 6.23.0 升级到 6.24.1作为底层 HTTP 依赖间接影响 OIDC 与 http-client 的网络行为。升级到 3.x 时请务必确认消费方的模块系统支持 ESM或改写为动态import()。十二、如何验证仓库内的测试支撑actions/core的功能均有完整测试覆盖可作为理解行为边界的权威参考packages/core/tests/core.test.ts —— 输入输出、环境文件命令、转义规则、注解映射、分组、setFailed 退出码、saveState/getState 等核心行为的 680 余行断言packages/core/tests/command.test.ts —— 命令字符串的转义与属性拼装packages/core/tests/summary.test.ts —— Job Summary 各 HTML 元素输出与文件写入packages/core/tests/path-utils.test.ts —— 路径转换packages/core/tests/platform.test.ts —— 平台信息与 getDetails。结语从 1.0.0 到 3.0.1actions/core的演进始终围绕两个目标让 Action 开发者以最少的样板代码完成标准工作流交互以及跟随 Runner 基础能力环境文件、Step Summary、OIDC、ESM同步现代化。对开发者而言重点掌握环境文件通道、::命令协议、注解属性与 ESM 迁移即可覆盖绝大多数 Action 开发场景更完整的 API 说明可继续阅读 packages/core/README.md 及仓库内其他包的 RELEASES.md 版本记录。赞分享CI/CD开发工具【免费下载链接】toolkitThe GitHub ToolKit for developing GitHub Actions.项目地址https://gitcode.com/gh_mirrors/to/toolkit点击查看免费下载相关推荐AI SDK Angular 组件库演进指南从 1.0 到 3.0 的版本变迁与核心 API 实战AI SDK Angular 组件库演进指南从 1.0 到 3.0 的版本变迁与核心 API 实战 ai sdk/angular 是 AI SDK 官方为人工智能AI 应用AI Agent工具调用MCP ClientsAsyncAPI规范版本演进指南从1.0到3.1.0的核心变化与升级策略AsyncAPI规范版本演进指南从1.0到3.1.0的核心变化与升级策略 AsyncAPI规范是描述异步API的行业标准它让开发者能够创建机器可读的异步APAPI设计后端从 1.0 到 3.0Guzzle Promisesguzzlehttp/promises版本演进、核心 API 变更与升级指南从 1.0 到 3.0Guzzle Promisesguzzlehttp/promises版本演进、核心 API 变更与升级指南 本文以仓库根目录下的 C后端上一篇QOwnNotes工具栏图标大小调整适应不同屏幕分辨率的完整指南下一篇migrate 数据库迁移工具 pgx 驱动PostgreSQL完整指南连接配置、多语句模式与锁机制源码剖析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考