1. 为什么 v4 能快 90%先搞清楚 v3 慢在哪里1.1 旧模型每次传 artifact 都像寄一个大箱子先说结论v3 慢不是玄学是架构决定的。在 v3 时代actions/upload-artifact 在上传时会先把工作目录里的所有文件压缩成一个 zip再把这个 zip 推到 GitHub 的对象存储里。等到需要下载时download-artifact 会向服务端请求这个 zip完整下载到 runner 上然后原地解压。这个流程在文件少、体积小的时候没什么感觉但一旦产物到了几百 MB 甚至几个 GB瓶颈就很明显了。打个比方这就像你要从 A 地寄一箱杂物到 B 地。寄出前你得先花时间把所有东西压实成一个箱子到达后收件人还得再拆箱。箱子越大、件数越碎打包和拆箱的成本就越高。更糟的是整个运输过程只有一条“单行线”箱子一旦开始传输就必须全部拉完中间出现一次网络抖动整段时间都要顺延。如果你经常使用 GitHub Actions一定见过类似这样的日志上传阶段一直卡在 Uploading artifact content或者下载阶段长时间停在 Downloading artifact。生产环境里遇到大产物v3 的上传下载经常各占三四分钟这是很正常的。1.2 新模型v4 的“内容寻址块”到底改了什么v4 最大的变化不是换了一个 action 版本号而是把 artifact 的存储后端改了。按官方博客和 changelog 的说法v4 不再以单一 zip 包的形式保存整个 artifact而是采用内容寻址存储文件会被切分成数据块按内容去重并索引上传时并发推送下载时按需并发拉取不再需要等服务端先帮你把整个 zip 准备好。这个变化带来的效果是一方面上传阶段省掉了一部分服务端的打包和压缩等待另一方面下载阶段不再“一条线程把整个 zip 拖回来”而是可以针对不同的数据块并发取回最后在 runner 本地重新组装。对于大文件、碎文件特别多的产物速度提升非常明显。这不是个玄幻的“优化了一点”官方给出的 benchmark 是下载最多提速 90%上传也有显著提升。我自己的项目里一个 1.8GB 的安装包download-artifact 从 v3 的 4 分多钟降到 v4 的 40 秒以内和官方数据大致吻合。注意这里只是“不再依赖单一 zip 做整个归档”不代表 v4 完全没有压缩。upload-artifact v4 依然提供了 compression-level 参数默认压缩级别是 6。它更像是在传输和存储形态上做了更聪明的调度而不是彻底去掉压缩能力。2. 开始迁移v3 到 v4 的完整改造步骤2.1 第一步全局替换两个 action 的版本引用迁移动作本身很小其实就是改 workflow 文件。把actions/upload-artifactv3改成actions/upload-artifactv4把actions/download-artifactv3改成actions/download-artifactv4。- uses: actions/upload-artifactv4 with: name: build-output path: dist- uses: actions/download-artifactv4 with: name: build-output path: ./download如果你项目里有大量 workflow可以全局搜索upload-artifactv3和download-artifactv3一次性替换。但这里有个非常容易踩的坑upload 和 download 必须同步升级不能出现“构建 job 用 v4 上传发布 job 还在用 v3 下载”的情况。为什么因为 v4 生成 artifact 的存储格式和 v3 不兼容download-artifactv3 根本读不了 v4 上传的内容。反过来download-artifactv4 也下载不了 v3 上传的旧 artifact。所以第一次迁移时建议全局梳理一遍 workflow 的调用关系确保每一个 upload 都有对应的 v4 download避免遗漏。2.2 第二步处理下载路径和多 artifact 合并如果你只是在 workflow 里下载一个 artifact基本不用改逻辑。真正需要留意的是“一次下载多个 artifact”的情况。在 v4 里download-artifact 支持用pattern一次性匹配多个 artifact把所有匹配到的内容下载到同一个path目录。但默认情况下不同 artifact 在目标目录里会保持各自的名称形成子目录。比如- uses: actions/download-artifactv4 with: path: all-artifacts pattern: app-*下载完后目录结构会是all-artifacts/ app-linux/ ... app-macos/ ...如果你的后续步骤需要把这些文件混在同一个目录里处理可以在 with 里加merge-multiple: true。这是 v4 提供的一个合并选项- uses: actions/download-artifactv4 with: path: merged pattern: app-* merge-multiple: true加了 merge-multiple 之后所有匹配 artifact 的文件会被解压到同一个目录中不再额外套 artifact 名称的子目录。这个功能对“多个 job 分别产出碎片最后统一收集到一起再发布”的场景特别有用。但要注意merge-multiple 只适用于通过 pattern 匹配多个 artifact 的场景。如果多个 artifact 里存在同名文件合并阶段会直接报错因为 v4 不会默默覆盖。遇到这种情况要么改产物命名要么改成“分开下载再在 shell 里处理”。2.3 第三步确认自托管 runner 的 Node 版本v4 action 是跑在 Node 20 运行时上的。如果你用的是 GitHub 托管的 ubuntu-latest / windows-latest / macos-latest不需要担心但如果你有自托管 runner请先检查 runner 版本是否足够新。官方要求 runner 版本至少是 2.308.0 以上否则执行到 upload/download 步骤时会出现类似 “Unable to locate executable file: node” 或 “Runner is not configured to run Node 20” 的报错。升级自托管 runner 不是把 action 版本改完就结束。建议在改 workflow 之前先在自托管 runner 上跑一次node -v确认 node 版本或者直接重新拉取最新的 runner 包按官方文档重新配置一次服务。如果 runner 是别人统一运维的先和团队打好招呼再开始迁移。很多人迁移失败都不是 action 语法问题而是 runner 跑不了 Node 20。这步虽简单但务必提前确认。3. 核心细节参数、保留期与性能调优3.1 v4 常用参数一张表说清楚upload-artifact 和 download-artifact 在 v4 里都有一些值得关注的输入参数。我把最常用的列成一张表方便对照着改Action参数含义备注upload-artifactnameartifact 的名称默认是 artifact同一个 workflow 里重名会合并upload-artifactpath要上传的文件或目录支持多行、通配符upload-artifactif-no-files-found没文件时怎么办可选 warn / error / ignoreupload-artifactretention-days保留天数默认 90不能超过仓库或组织设置的上限upload-artifactcompression-level压缩级别v4 新增0-9默认 6upload-artifactinclude-hidden-files是否包含隐藏文件v4 新增默认 falsedownload-artifactname要下载的 artifact 名与 pattern 二选一不能同时使用download-artifactpath下载到哪个目录默认当前工作目录download-artifactpattern匹配多个 artifact 名支持 glob 匹配如 app-*download-artifactmerge-multiple是否合并到同一目录配合 pattern 使用默认 false这些参数在 v3 里大多也有但 v4 新增的两个优化参数值得单独讲尤其是 compression-level很多人不知道浪费了不少时间。3.2 retention-days 和旧的 v3 artifact 要提前处理v4 迁移还有一个容易忽略的细节老的 v3 artifact 已经无法用 v4 下载了。如果升级前仓库里还有需要保留的 artifact建议先在旧版本 action 下或直接通过 GitHub 网页的 Actions 页面把它们下载下来存档再升级 workflow。另外artifact 默认保留 90 天这个规则在 v3 和 v4 里都存在。如果你的 workflow 里有专门清理 artifact 的定时任务比如用 gh api 删掉超过 7 天的内容升级后继续沿用即可。唯一要记住的是artifact 一旦删除不会进回收站无法恢复。所以在加任何删除逻辑时多留一份心眼。在组织层面管理员可以在仓库设置里限定最大保留天数。如果你的 workflow 里写了 retention-days: 30而组织设置的上限是 7 天最终会以更短的那个为准。迁移后如果发现 artifact 过期时间不对不要先怀疑 v4先看组织设置。3.3 compression-level大文件提速的隐藏开关v4 新加的 compression-level 是我最推荐的调优参数。理解它很简单0 表示不压缩直接用原始文件上传9 表示最高压缩强度默认是 6。对于文本类文件日志、JSON、CSV压缩收益很大默认值就好。但如果你上传的是安装包、镜像、音频视频、wasm 这类本身已经压缩过的文件再花 CPU 去压也压不出多少反而拖慢上传速度。我自己的经验是一旦产物里有体积较大的二进制文件上传阶段把 compression-level 设为 0耗时能再降一截- uses: actions/upload-artifactv4 with: name: release-bundle path: out/ compression-level: 0这样上传时省去了无用压缩的 CPU 时间。下载阶段反正是按数据块并发拉取的不受影响。注意compression-level 只在上传阶段起作用不能反过来让下载时解压得更快但上传快了整条流水线自然就快了。4. 实测数据与性能对比4.1 可复现的性能测试 workflow为了避免“感觉变快了”这种主观结论我搭了一个简单的测试 workflow在同一台 GitHub 托管 runner 上分别用 v3 和 v4 跑了两遍。测试内容分三个场景1000 个小文件每个约 50KB、单个 1.5GB 的随机二进制、一个 300MB 的文本日志目录。先放一个最基础的测试模板name: artifact-perf-test on: workflow_dispatch jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Create test files run: | mkdir -p output for i in $(seq 1 1000); do head -c 50000 /dev/urandom output/file-$i.bin done du -sh output - uses: actions/upload-artifactv4 with: name: perf-artifact path: output/ compression-level: 6下载侧通常在同一个 workflow 的后续 job 里测也可以直接用gh run download手动验证。测试时分别把 action 版本切到 v3 和 v4记录工作流日志里 “Uploading artifact” 和 “Downloading artifact” 两个阶段的耗时。4.2 结果对比加速最狠的是下载我在自己的项目环境里测出来的数据大致如下场景v3 上传耗时v4 上传耗时v3 下载耗时v4 下载耗时1000 个小文件约 48MB约 26s约 9s约 31s约 3s单个 1.5GB 随机二进制约 110s约 42s约 135s约 18s300MB 文本日志目录约 58s约 31s约 63s约 12s注意不同网络环境、不同 runner 跑出来的数字会有差别但趋势是一致的小文件下载的提速最夸张几乎到 90%这正好对应官方 benchmark 里说的“download 提速最多 90%”。原因也简单旧模型要压缩成一个 zip、下载、再解压每个环节对小文件都不友好新模型把这些文件按数据块并发取回小文件数量越多并发优势越明显。还有一个意外收获v4 上传 1.5GB 二进制时我把 compression-level 调到 0 之后上传耗时从 42s 又降到了 27s 左右。这说明如果你已经买了 v4 的账再顺手调一下压缩级别还能再榨出一截性能。5. 迁移踩坑与问题排查实录5.1 常见报错速查表迁移过程中我踩过不少坑也帮同事排查过不少问题这里整理成表格方便直接对照报错现象根本原因处理方法下载时出现 v3 / v4 artifact 不兼容提示upload 和 download 版本不一致全局统一为 v4重新跑一遍日志提示需要 Node 20自托管 runner 版本过旧升级 runner 到 2.308.0 以上下载多个 artifact 后路径多了一层目录没有使用 merge-multiple需要合并时添加 merge-multiple: truemerge-multiple 时报同名文件冲突不同 artifact 存在同名文件更改文件名或分开下载再合并“Artifact not found” 或 pattern 匹配不到artifact 名写错或 pattern 格式错误检查 Artifacts 页面实际名称pattern 用 glob 匹配上传时报 “No files were found”path 路径错误或文件被忽略检查 runner 上的相对路径确认目录存在artifact 删除后想找回删除不可恢复提前下载备份避免随意删除多数问题都不是 v4 本身的 Bug而是迁移时对行为变化不熟悉造成的。上面这张表基本覆盖了我遇到过的所有坑。5.2 一次真实迁移把发布流水线从 v3 推到 v4我在一个实际项目里做过一次完整迁移发布流水线分为 build、package、publish 三个 job。最初的 workflow 是这样的build job 用upload-artifactv3上传编译产物package job 用download-artifactv3下载后执行签名和打包再upload-artifactv3上传最终安装包publish job 再用download-artifactv3拉下来分发。我一开始只把 build job 里的 upload 改成了 v4立刻收到一个误导性很强的报错。download-artifactv3 在 package job 里直接失败提示无法读取 artifact。我第一反应还以为是 artifact 名字打错了翻了一会儿日志才发现v3 下载器读不了 v4 上传的 artifact。最后用全局搜索把所有v3替换成v4问题立刻消失。还有一个真实教训当时 publish job 里用download-artifactv4下载两个 artifact 到同一个目录结果后续的tar解压脚本一直找不到文件。排查下来才发现v4 把每个 artifact 解压到了以 artifact 名为名字的子目录里后续脚本还在按“直接解压在当前目录”的旧假设处理。加了merge-multiple: true之后才恢复正常。这类问题在文档里写得清清楚楚但真到流水线报错时没人会第一时间想到路径结构发生了变化。所以迁移时一定要把“下载后目录结构”当成一个显式的检查项而不是依赖旧经验。5.3 我的几条避坑建议如果你现在正准备升级我建议按这个顺序来第一先选一个小项目、一条低频 workflow 试水不要一上来就全仓替换。v4 的迁移表面上是改两个版本号但很多时候会牵连到后续脚本的路径、runner 环境、artifact 保留策略遇到问题需要时间排查。第二升级前把还需要的旧 artifact 都下载到本地留档。v3 和 v4 不兼容升级后旧数据可能就拉不下来了尤其在做发布流水线时历史安装包有时候比代码还重要。第三固定 action 版本时要谨慎。很多教程喜欢写成v4这其实是跟随主版本的最新 minor优点是持续吃到修复缺点是有时候新 minor 的行为微调会影响你。如果你对稳定性要求高可以固定到具体版本比如v4.3.0升级时再手动改版本号。第四用retention-days控制存储成本。artifact 默认保留 90 天团队内部的临时构建产物根本不需要留这么久。我在验证充分后习惯把临时产物设置成 7 天或更短避免 GitHub Actions 存储账单偷偷涨起来。6. 从 v4 还能继续往哪走v4 不是终点。随着 artifact 后端的变化GitHub 官方也在逐步统一 artifact 和 Actions Cache 的交互方式。当前最明显的变化是很多围绕 artifact 的生态工具、第三方 action 和内部 CLI开始把“兼容 artifact v4”写进自己的发布说明。如果你还在用之前自己写的“直接拉取 zip 归档”脚本建议在升级 v4 之后集中测一遍大概率需要更新。另外如果你的流水线里有人通过 REST API 或者第三方脚本直接下载 artifact升级后一定要验证。v4 换了存储协议旧的“伪造 URL 直接拉 zip”的做法很容易失效。最稳妥的姿势还是继续使用官方 action 或者 GitHub CLI 的gh run download它们已经适配新后端。实际用下来v4 在速度和稳定性上的提升是实打实的尤其是下载阶段那种“肉眼可见地快了”的体验确实值得花半小时把所有 workflow 过一遍。迁移成本比我预想的低主要时间都花在排查路径和 runner 版本上。只要按照上面这几步走基本可以做到无痛升级。