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）：
| 通道 | 版本 | 说明 |
|---|---|---|
稳定版 h3 |
2.0.8 |
2026-10-22 发布 |
h3-nightly 的 latest |
2.0.0-20260903-101917-849fa36 |
构建于 2026-09-03 |
h3-nightly 的 1x 标签 |
1.15.12-20260519-122018-9aa6f55 |
v1 线的夜间构建 |
注意第一行和第二行的时间：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 里可能新增或调整：
| 子路径 | 用途 |
|---|---|
h3 |
主入口（H3、工具函数） |
h3/node、h3/bun、h3/deno、h3/cloudflare、h3/service-worker、h3/generic |
各运行时适配 |
h3/rules、h3/rules/cache、h3/rules/proxy |
路由规则与自定义处理器工厂 |
h3/tracing |
追踪相关 |
如果你的代码 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 的新接口。
什么时候值得用
| 值得 | 不值得 |
|---|---|
| 你提的 issue 已经有修复提交 | 只是想「用最新版」 |
| 想提前适配下一个大版本的破坏性变更 | 生产环境 |
| 在库里做兼容性测试（CI 一条腿） | 没有测试覆盖的项目 |
| 排查某个只在主分支复现的 bug | 依赖链很深、升级成本高的项目 |
最后补一句现实提醒：从仓库 Git 地址直接安装拿不到现成产物——发布包的 files 只含 dist，构建挂在 prepack 上。所以实践里就走 npm:h3-nightly，别自己从源码装。
排查表
| 现象 | 最可能原因 | 处理 |
|---|---|---|
| 装完发现版本号没变 | lockfile 没更新 | 删掉该条 lock 记录或 pnpm update h3 |
报 Cannot find module 'h3/rules/cache' |
该子路径在 nightly 里被调整 | 查 nightly 的 exports 字段 |
| 启动即报 srvx 相关属性错误 | 连带依赖版本不匹配 | 同步升级 srvx |
| CI 每次结果都不一样 | 用了 @latest |
锁到具体构建号 |
| 想回滚却回不去 | 只改了 overrides 但没重装 | 删 overrides 后重装依赖 |
延伸阅读
- 从 v1 升到 v2 要改的 API：见 8.1 v1 到 v2 迁移：核心变更
- 实例配置项与运行期行为：见 4.1 应用实例 API
- WebSocket 需要的 crossws 也是 peer 依赖：见 5.2 WebSocket 与 SSE