GitHub Actions Toolkit 制品（Artifact）FAQ 实战指南：非法字符校验、ZIP 压缩策略、版本兼容与保留期

CI/CD开发工具【免费下载链接】toolkitThe GitHub ToolKit for developing GitHub Actions.项目地址https://gitcode.com/gh_mirrors/to/toolkit点击查看免费下载导读本文以 GitHub Actions Toolkit 中actions/artifact包的官方 FAQ 文档仓库路径 packages/artifact/docs/faq.md为骨架逐条拆解 GitHub Actions 制品上传/下载中最高频的四个问题制品名称与路径允许哪些字符、制品如何被压缩存储、upload-artifact与download-artifact的版本兼容关系、制品默认保留多久。结合仓库源码path-and-artifact-name-validation.ts、zip.ts、retention.ts与测试用例给出可直接落地的配置参数、默认值和踩坑清单。读完本文你将能够正确命名制品、按需调节压缩级别、选择匹配的 action 版本组合并准确控制制品的生命周期。actions/artifact是驱动actions/upload-artifact与actions/download-artifact两个官方 Action 的核心库位于仓库 packages/artifact当前版本为6.3.1见 package.json。它提供uploadArtifact、downloadArtifact、listArtifacts、getArtifact、deleteArtifact五个编程接口入口定义在 client.ts默认实例导出自 artifact.ts。一、支持的字符制品名称与路径的非法字符限制1.1 规则总览上传制品时传入的name参数制品名称以及files中指定的文件路径均不能包含以下 7 个字符。只要name或files中出现其中之一制品就会被服务器拒绝上传失败非法字符名称双引号 Double quote:冒号 Colon小于号 Less than大于号 Greater than|竖线 Vertical bar*星号 Asterisk?问号 Question mark额外限制除上述 7 个字符外制品名称name还不能包含\反斜杠与/正斜杠。注意文件路径中允许出现\和/它们本就是路径分隔符只是不允许出现在制品名称中。1.2 为什么这样限制这些字符被禁止是因为部分文件系统如 Windows 的 NTFS存在命名限制。为了保持**平台无关platform-agnostic**行为凡是个别文件系统/平台不支持的字符就统一在所有文件系统/平台上禁止。这样制品在任何平台上下载解压时都不会因文件名非法而导致失败。1.3 源码级校验实现校验逻辑实现在 path-and-artifact-name-validation.tsinvalidArtifactFilePathCharacters定义文件路径禁止的 9 个字符上述 7 个之外额外包含\r回车符与\n换行符见源码第 11–21 行invalidArtifactNameCharacters在文件路径非法字符基础上再追加\与/构成制品名称的 11 个非法字符见源码第 23–27 行validateArtifactName(name)校验制品名称为空名或包含非法字符时直接抛出Error源码第 32–55 行validateFilePath(path)校验文件路径同样为空路径或包含非法字符时抛出Error源码第 60–82 行。在校验通过时库会通过actions/core输出日志Artifact name is valid!校验失败的错误信息中会列出所有非法字符并说明“为保持跨文件系统行为一致这些字符被有意禁止”。1.4 测试用例印证path-and-artifact-name-validation.test.ts 用两组用例验证了上述规则名称非法样例my\artifact、my/artifact、myartifact、my:artifact、myartifact、myartifact、my|artifact、my*artifact、my?artifact以及空字符串均toThrow()名称合法样例my-normal-artifact、myNormalArtifact以及包含非 ASCII 字符的m¥ñðrmålÄr†ï£å¢†均不抛出异常说明非 ASCII 字符是允许的路径非法样例some/invalidartifact/path、some/invalid:artifact/path、含\r、\n、\r\n的路径等均报错路径合法样例my/perfectly-normal/artifact-path、my/perfectly\Normal/Artifact-path等均通过。1.5 校验在完整上传链路中的位置字符校验只是上传流程的第一步。在 upload-artifact.ts 的uploadArtifact中第 54–55 行依次调用validateArtifactName(name)与validateRootDirectory(rootDirectory)随后getUploadZipSpecification在生成 ZIP 结构时还会对每个要打包的文件相对路径再次调用validateFilePath见 upload-zip-specification.ts 第 100、110 行。也就是说名称与路径会在打包前被双重校验。实战建议命名制品时使用小写字母、数字、连字符与点号即可安全跨平台不要在名称中使用空格以外的特殊符号尤其避开上表列出的 11 个字符。二、压缩与存储制品是如何被打包成 ZIP 的2.1 动态压缩、流式上传创建制品时文件会被动态压缩并流式streamed写入一个 ZIP 归档。既然是 ZIP 归档就可以通过 Zlib 以不同级别压缩。核心实现在 zip.ts默认压缩级别常量DEFAULT_COMPRESSION_LEVEL 6源码第 8 行createZipUploadStream(uploadSpecification, compressionLevel DEFAULT_COMPRESSION_LEVEL)调用archiver.create(zip, {highWaterMark: ..., zlib: {level: compressionLevel}})创建归档流第 10–21 行对符号链接会先通过fs.realpath解析为真实路径再打包第 33–35 行空目录以zip.append(, {name: destinationPath})的形式保留第 42–44 行压缩流经WaterMarkedUploadStream边压缩边上载到 Blob 存储实现“边打包边传”无需整包落盘。2.2 压缩级别 0–9 的含义compressionLevel取值范围为 0 到 9值含义说明0无压缩上传速度最快但存储体积最大1最快速度压缩率低、速度快6默认压缩与 GNU Gzip 相同createZipUploadStream的默认值9最佳压缩压缩率最高但耗时最长级别越高压缩效果越好但耗时也越长。对于不易压缩的大文件官方建议直接使用 0可获得显著更快的上传速度——这本质上是在“上传耗时”与“存储体积”之间做取舍。2.3 在编程接口中使用选项定义在 interfaces.ts 的UploadArtifactOptions.compressionLevel中注释与 FAQ 完全一致第 43–52 行。使用示例import {DefaultArtifactClient} from actions/artifact const artifact new DefaultArtifactClient() // 大体积、不可压缩的二进制文件关闭压缩换取上传速度 await artifact.uploadArtifact(my-massive-artifact, [big_file.bin], { compressionLevel: 0 // 0 无压缩 | 1 最快 | 6 默认(与 GNU Gzip 相同) | 9 最佳 }) // 文本类可压缩内容追求最小存储体积 await artifact.uploadArtifact(my-logs, [app.log], { compressionLevel: 9 })当未显式传入compressionLevel时upload-artifact.ts 第 107–110 行将undefined直接传给createZipUploadStream由函数默认值 6 兜底——即默认与 GNU Gzip 同级压缩。2.4 与压缩相关的其他实现细节分块上传getUploadChunkSize()config.ts 第 6–8 行固定返回8 * 1024 * 10248 MB既作为 ZIP 流的highWaterMark也作为上传 Blob 存储的块大小skipArchive 选项UploadArtifactOptions.skipArchiveinterfaces.ts 第 54–59 行支持“不压缩直接上传单个文件”此时制品名称改用文件名本身且文件不经过 Zlib 压缩。该能力自actions/artifact6.2.0 起提供见 RELEASES.md目前仅支持单文件上传下载端自动解压下载时若检测到application/zip等 MIME 类型或 URL 以.zip结尾download-artifact.ts 第 89–93、159–164 行会通过unzip-stream边下载边解压到目标目录也可用DownloadArtifactOptions.skipDecompress关闭自动解压按原样保存第 165–171 行。三、版本兼容upload-artifact 与 download-artifact 如何配套3.1 兼容矩阵actions/upload-artifact与actions/download-artifact都依赖 GitHub Actions Toolkit通常成对使用来完成工作流中的制品上传与下载。FAQ 给出的兼容矩阵如下upload-artifactdownload-artifacttoolkitv4v4v2 v3 v3 v1请务必使用相互匹配的actions/upload-artifact与actions/download-artifact版本以确保兼容。也就是说上传用 v4下载也要用 v4对应 toolkit v2而老版本小于 v3则对应 toolkit 小于 v1 的版本。3.2 工作流 YAML 中的写法在 GitHub Actions 工作流的 YAML 文件中通过uses指定 action 版本steps: - name: 上传制品 uses: actions/upload-artifactv4 with: name: my-artifact path: ./dist - name: 下载制品 uses: actions/download-artifactv4 with: name: my-artifact发布说明Release Notes官方建议在升级前查看两个仓库各自的发布说明确认是否存在关于兼容性或者行为变更的具体提示。例如 RELEASES.md 中记录actions/artifact6.0.0 起包改为ESM-onlyCommonJS 消费者必须改用动态import()6.1.0 起支持下载非 ZIP 制品6.2.0 起支持skipArchive单文件直传。这些都是可能影响下游 Action 的行为变更。3.3 版本背后的架构变化为什么 v4/v4 要配 toolkit v2因为actions/artifactv2对应upload-artifactv4、download-artifactv4对制品后端架构做了重大重构详见 README.md上传/下载显著提速最坏场景下下载最多快约 80%、上传最多快约 96%上传完成后立即返回制品 ID制品马上可在 UI 与 REST API 中可见无需等待整个 run 结束制品内容以不可变归档整体上传后续 job 无法篡改支持携带具备actions:read权限的 token 从其他仓库/其他 run下载制品findBy选项引入新限制同一 run 内不允许向同名制品重复上传单个 job 的制品数量上限为 10 个当前 v2 体系在 GHESGitHub Enterprise Server上尚未受支持。这些行为变更正是“必须成套升级”的底层原因。四、保留期制品默认可用多久4.1 默认值制品的默认保留期为90 天。这是 GitHub Actions 的默认设置超出期限后制品会被自动清理。4.2 通过 retentionDays 覆盖默认值在编程接口中可通过UploadArtifactOptions.retentionDaysinterfaces.ts 第 25–41 行覆盖默认保留期最小值为 1最大值通常为 90具体上限受仓库/组织设置约束如果传入的值大于服务器允许的最大保留天数服务器会把保留期下调为最大值并继续上传不会失败并打印警告传入 0 表示采用默认保留设置。await artifact.uploadArtifact(my-artifact, [file1.txt], { // 例如只保留 10 天 retentionDays: 10 })4.3 源码实现getExpiration保留期计算实现在 retention.ts 的getExpiration未传retentionDays时直接返回undefined第 4–8 行请求中不带过期时间由服务端按默认 90 天处理读取环境变量GITHUB_RETENTION_DAYS得到仓库允许的最大保留天数maxRetentionDays第 23–34 行若maxRetentionDays存在且小于请求值输出警告并强制使用maxRetentionDays第 9–15 行最终以“当前时间 保留天数”构造Timestamp作为过期时间第 17–20 行。该expiresAt会被写入CreateArtifactRequest见 upload-artifact.ts 第 87–90 行随创建制品的 RPC 请求一起发给服务端。4.4 测试用例印证retention.test.ts 覆盖了四种场景传入 30 天且GITHUB_RETENTION_DAYS90返回当前时间 30 天的过期时间传入 120 天且GITHUB_RETENTION_DAYS90被截断为当前时间 90 天不传参数返回undefined无最大保留天数限制时传入 30 天正常返回 30 天。实战建议需要长期保留的产物请明确在仓库设置中调大保留上限后再传对应retentionDays临时调试用制品尽量设置较短的保留期避免占用存储配额。五、总结四个高频问题的速查表问题答案制品名称/路径不能含什么字符名称禁含:|*?\/路径禁含:|*?\r\n。原因NTFS 等文件系统限制 平台无关策略制品如何存储动态压缩为 ZIP 并流式上传Zlib 压缩级别 0–9默认 6同 GNU Gzip大且难压缩的文件建议用 0 换取上传速度6.2.0 支持skipArchive单文件不压缩直传版本如何配套upload-artifact v4 配 download-artifact v4 配 toolkit v2小于 v3 的旧版本配 toolkit 小于 v1。升级前务必查看双方 Release Notes制品保留多久默认 90 天可用retentionDays覆盖≥1上限受仓库设置约束超限自动下调并警告0 表示用默认如需进一步了解编程接口的完整 API可查阅 生成文档本文涉及的所有校验、压缩、保留期逻辑均可在 packages/artifact/src/internal 及其对应 测试目录 中复现验证。赞分享CI/CD开发工具【免费下载链接】toolkitThe GitHub ToolKit for developing GitHub Actions.项目地址https://gitcode.com/gh_mirrors/to/toolkit点击查看免费下载相关推荐GitHub Actions 版本管理实战指南ref 绑定、主版本兼容与发布策略Toolkit 视角GitHub Actions 版本管理实战指南ref 绑定、主版本兼容与发布策略Toolkit 视角 本指南以 GitHub Actions ToolkiCI/CD开发工具nektos/act版本兼容支持不同GitHub Actions版本的策略nektos/act版本兼容支持不同GitHub Actions版本的策略 痛点与挑战 你是否曾经遇到过这样的困境在本地使用nektos/act测试GitHCI/CDDevOps开发工具CLIandroidannotations资源压缩与注解保留策略androidannotations资源压缩与注解保留策略 在Android开发过程中资源优化和注解处理是提升应用性能的关键环节。AndroidAnnotat移动开发代码生成上一篇civitai 审核查询移植全景清单主应用到 civitai/db-queries 的收敛Convergence与 Net-new 实战指南下一篇DeepSeek Harness TUI 交互扩展服务基于 ctx.tui.openOverlay() 的模态浮层插件原语创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考