mcpField
U
update-v8

update-v8

github.com/cloudflare开发9.1k50 次安装今天更新
代码仓库

关于 update-v8

用于更新 workerd 中 V8 的流程技能，面向维护其 V8 依赖的开发者。它涵盖补丁变基、依赖更新、构建和测试，并要求高风险决策经人工确认。

主要功能

  1. 01与开发者确认目标 V8 版本
  2. 02将 workerd 补丁变基到新 V8
  3. 03重新生成并更新补丁文件
  4. 04更新 V8 依赖固定版本
  5. 05构建并测试 workerd

适用场景

  1. 01准备 workerd 的 V8 版本更新
  2. 02审查并处理补丁冲突
  3. 03在 V8 变更后检查构建和测试

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cloudflare/workerd --skill update-v8

安装后在 Claude Code 中输入/update-v8确认已加载。

详细介绍

更新 workerd 中的 V8

V8 更新属于高风险变更，需要谨慎管理补丁，并由人工判断如何解决合并冲突。本指南涵盖完整流程。开始前务必与开发者确认目标版本。

另请参阅 V8 更新参考。

务必在每个步骤与开发者沟通并确认。 未经明确确认，切勿执行不可逆操作（例如删除补丁或更新哈希）。

前置条件
  • 已安装 depot_tools，且位于 $PATH 中（安装指南）
  • 本地 V8 检出目录（位于 workerd 仓库之外，以免与 Bazel 混淆）： 
    mkdir v8 && cd v8 && fetch v8
步骤 1：确定目标版本

查看 chromiumdash.appspot.com，确认 Chrome Beta 使用的最新 V8 版本。与开发者确认目标版本 <new_version>。

在 build/deps/v8.MODULE.bazel 中查找当前版本：

VERSION = "14.5.201.6"    # example — check the actual file

我们将其称为 <old_version>。

步骤 2：将本地 V8 同步到当前 workerd 版本
cd <path_to_v8>/v8
git checkout <old_version>
gclient sync
步骤 3：将 workerd 的补丁应用到分支上
git checkout -b workerd-patches
git am --keep-non-patch <path_to_workerd>/patches/v8/*

patches/v8/ 中有多个补丁，包括 workerd 专用的定制：

补丁类别示例
序列化自定义 ValueSerializer/Deserializer 格式版本、代理/函数宿主对象支持
构建系统Windows/Bazel 修复、共享链接、依赖路径覆盖（fp16、fast_float、simdutf、dragonbox）
Embedder 钩子Promise 上下文标记、跨请求 Promise 解析、额外的 isolate embedder 槽位
Bug 规避方案禁用内存泄漏断言、禁用慢速句柄检查、builtin-can-allocate 规避方案
API 新增项暴露 String::IsFlat、AdjustAmountOfExternalAllocatedMemory，新增 Exception 构造函数
ICU/配置导出 ICU 数据、绑定 googlesource ICU、verify_write_barriers 标志
步骤 4：将补丁变基到新版 V8 上
git rebase --onto <new_version> <old_version>

大部分工作都在这一步。 请预期会遇到冲突。关键指导：

  • 构建系统补丁（依赖路径、Bazel 配置）最容易发生冲突，因为上游 V8 会重构其构建系统。
  • API 补丁（在 V8 类中新增方法）如果上游改动了相邻代码，也可能发生冲突。
  • 务必保留 workerd 的意图——解决冲突前，先了解每个补丁的作用。补丁文件名具有说明性。
  • 未经开发者明确确认，不要删除补丁。
  • 不要自动解决冲突——将其标记出来，交由人工审查。V8 补丁中的合并冲突几乎总是需要人工判断。
步骤 5：重新生成补丁
git format-patch --full-index -k --no-signature --no-stat --zero-commit <new_version>

这会在当前目录生成带编号的 .patch 文件。

步骤 6：替换 workerd 中的补丁

替换补丁前，务必先与相关人员确认。如果有补丁被删除或新增， 相关人员需要审查这些更改。

rm <path_to_workerd>/patches/v8/*
cp *.patch <path_to_workerd>/patches/v8/
步骤 7：更新 build/deps/v8.MODULE.bazel

需要更新三项：

  1. VERSION：设置为 <new_version>。

  2. INTEGRITY：计算新 tarball 的 sha256 哈希：

    curl -sL "https://github.com/v8/v8/archive/refs/tags/<new_version>.tar.gz" -o v8.tar.gz
openssl dgst -sha256 -binary v8.tar.gz | openssl base64 -A

    格式："sha256-<base64_hash>="。也可以尝试构建，并从 Bazel 的哈希不匹配错误中复制预期哈希。

  3. PATCHES：如果补丁有新增、删除或重命名，请更新列表。列表必须与 patches/v8/ 中的文件名完全一致，且顺序相同。

第 8 步：更新 V8 的依赖项

V8 依赖于几个固定在 build/deps/v8.MODULE.bazel 和 build/deps/deps.jsonc 中的库。检查本地 V8 检出目录中的 DEPS 文件，确认提交版本：

cat <path_to_v8>/v8/DEPS

需要检查和更新的依赖项：

依赖项位置说明
com_googlesource_chromium_icuv8.MODULE.bazel（git_repository commit）Chromium 分支；根据 V8 的 DEPS 更新提交
perfettodeps.jsonc（由 update-deps.py 管理）V8 通过 Chromium 依赖此项；可以安全地升级到 GitHub 上的最新版本
simdutfdeps.jsonc（由 update-deps.py 管理）V8 通过 Chromium 依赖此项；可以安全地升级到 GitHub 上的最新版本

对于 deps.jsonc 中的依赖项，可以使用更新脚本：

python3 build/deps/update-deps.py perfetto
python3 build/deps/update-deps.py simdutf

该脚本会获取最新版本、计算完整性哈希，并重新生成 gen/ MODULE.bazel 片段。不要手动编辑 build/deps/gen/ 中的文件。

第 9 步：构建和测试
# Full build
just build

# Full test suite
just test

请留意：

  • V8 API 变更导致的构建失败：V8 可能会在不同版本间弃用或更改 API。请在构建输出中查找弃用警告。常见受影响区域：

    • src/workerd/jsg/ — V8 绑定层，受影响最直接
    • src/workerd/api/ — 直接与 V8 类型交互的 API
    • src/workerd/io/worker.c++ — Isolate 的创建和配置

  • 行为变更导致的测试失败：V8 可能会改变可观察到的 JS 行为。请检查：

    • just test //src/workerd/jsg/... — JSG 绑定测试
    • just test //src/workerd/api/tests/... — API 测试
    • Node.js 兼容性测试（just node-test）
    • Web Platform Tests（just wpt-test）

  • 新增的 V8 弃用警告：这些警告预示着未来可能出现问题。即使测试通过，也要在 PR 描述中记录。

第 10 步：提交并发起审查

提示用户提交更改并推送以供审查。

未经人工审查补丁更改，切勿推送分支以供审查。

你可以为用户准备 PR 草稿。PR 应包括：

  • 更新后的 build/deps/v8.MODULE.bazel（版本、完整性、补丁列表）
  • 更新后的 patches/v8/ 中的补丁
  • 更新后的依赖项版本（如有更改）
  • 针对 V8 API 变更所做的任何 C++ 修复
  • PR 描述，列出：旧版本、新版本、需要解决冲突的补丁、观察到的任何弃用警告，以及注意到的任何行为变更
检查清单
  • 已与开发人员确认目标 V8 版本
  • 已在本地检出 V8，并同步到旧版本
  • 已应用 workerd 补丁，并将其变基到新版本
  • 已通过人工审查解决冲突（不自动解决）
  • 已使用 git format-patch 重新生成补丁
  • 已用新补丁替换 patches/v8/ 中的旧补丁
  • 已更新 v8.MODULE.bazel 中的 VERSION
  • 已更新 v8.MODULE.bazel 中的 INTEGRITY
  • 如果补丁有新增、删除或重命名，已更新 PATCHES 列表
  • 已检查并更新 V8 依赖项（ICU、perfetto、simdutf）
  • just build 成功
  • just test 通过（或已记录并说明失败原因）
  • 未经明确确认，没有丢弃任何新补丁
  • PR 描述记录了版本变更、冲突解决情况和弃用警告
故障排除

Bazel 完整性不匹配：如果看到 expected sha256-... but got sha256-...，请将“got”哈希值复制到 INTEGRITY 字段。这通常是因为哈希值计算错误，或者 GitHub 重新生成了压缩包。

补丁无法应用：如果补丁在 git am 期间可以顺利应用，但在 Bazel 中失败，说明 git format-patch 的输出与 Bazel 预期的不一致。请确认使用了 --full-index -k --no-signature --no-stat --zero-commit 标志。还请确认补丁顺序与 PATCHES 列表一致。

ICU 构建失败：ICU 是通过 git_repository 获取的 Chromium 分支。如果 v8.MODULE.bazel 中的提交版本有误，ICU 中就会出现文件缺失或编译错误。请参照 V8 的 DEPS 文件，确认正确的提交版本。

update-deps.py 失败：该脚本需要联网获取版本信息。如果某个依赖项的 GitHub 发布格式发生变化，可能需要在 deps.jsonc 中手动更新版本，然后运行 python3 build/deps/update-deps.py 重新生成哈希值。

评论

支持 Markdown