H3 Nightly 构建与预发布通道

稳定版发布之间，H3 会把主分支的每次提交自动发到 h3-nightly 这个包里。它用的还是同一份代码，只是版本号带了时间戳和提交哈希，方便你「提前一天用上还没发布的东西」。

一行切过去

官方给的方式就是改依赖指向，包名换成 npm 别名：

{
  "dependencies": {
    "h3": "npm:h3-nightly@latest"
  }
}

改完重装依赖即可生效，代码一行都不用动——import { H3 } from "h3" 保持不变，因为 npm 别名让 h3 这个位置解析到了 h3-nightly。

但 nightly 不等于「更新」，这点要先看清

实测两个通道的版本号（2026-10-30 查询 npm registry）：

注意第一行和第二行的时间：nightly 的时间戳比稳定版更早。原因是夜间通道跟踪的是「下一条版本线」的预览，一旦正式版发出去，这条线就停下来等下一个大版本，而稳定版继续打补丁（2.0.1 到 2.0.8 都在 nightly 之后）。

所以切 nightly 前先回答一个问题：你要的是「比 2.0.8 更新的补丁」还是「下一个大版本的早期形态」？ 前者去升级稳定版就好，后者才是 nightly 的用途。

版本号怎么读

2.0.0     - 20260903 - 101917 - 849fa36
主版本.次版本  构建日期    时分秒    commit 短哈希

时间戳到秒、带 commit 哈希，这意味着两件事：可以精确定位到某次构建，也可以随时回退到某个具体时间点。

三条实践建议

① 别用 @latest，锁到具体构建。

{
  "devDependencies": {
    "h3": "npm:h3-nightly@2.0.0-20260903-101917-849fa36"
  }
}

@latest 每次安装都可能拿到不同的构建，CI 会莫名其妙地飘。锁死之后，升级是一次显式的提交。

② 用 overrides 局部试，不要动主依赖。

{
  "pnpm": {
    "overrides": {
      "h3": "npm:h3-nightly@2.0.0-20260903-101917-849fa36"
    }
  }
}

这样 dependencies 里仍是稳定版声明，只在本地或某条 CI 上覆盖。npm 用同名的 overrides 字段，效果一致。好处是回滚只需删掉这段，不用改业务依赖。

③ 单独放一条 CI 任务，别污染主矩阵。

## 主矩阵跑稳定版；这一条只跑 nightly，允许失败
jobs:
  nightly:
    continue-on-error: true
    steps:
      - run: pnpm add -D h3@npm:h3-nightly@latest
      - run: pnpm test

continue-on-error 是关键：nightly 本来就是未完成的代码，失败是信息而不是阻塞。

切之前先确认两件事

第一，子路径导入是否还在。 h3 的 exports 暴露了多个入口，nightly 里可能新增或调整：

如果你的代码 import 了 h3/rules/cache 这类子路径，升 nightly 前先确认它还在。

第二，连带依赖的版本。 h3 依赖 srvx 与 rou3，并把 crossws、ocache 声明为 peer 依赖。nightly 可能要求更高的 srvx，这时要同步升：

## 先看 nightly 要求什么，再决定 srvx 要不要一起升
npm view h3-nightly@latest dependencies
npm view h3-nightly@latest peerDependencies

漏升 srvx 的典型症状是运行时在 toNodeHandler 或请求对象上抛奇怪的属性错误——因为新代码依赖了 srvx 的新接口。

什么时候值得用

最后补一句现实提醒：从仓库 Git 地址直接安装拿不到现成产物——发布包的 files 只含 dist，构建挂在 prepack 上。所以实践里就走 npm:h3-nightly，别自己从源码装。

排查表

延伸阅读

• 从 v1 升到 v2 要改的 API：见 8.1 v1 到 v2 迁移：核心变更
• 实例配置项与运行期行为：见 4.1 应用实例 API
• WebSocket 需要的 crossws 也是 peer 依赖：见 5.2 WebSocket 与 SSE