Bun v1.3.11 官方更新全整理：新增功能、关键修复与升级验证

Bun v1.3.11 官方更新全整理：新增功能、关键修复与升级验证

摘要

Bun v1.3.11 不是“小修小补”版本，而是一次“功能新增 + 兼容修复 + 工程稳定性”集中迭代。很多团队升级后只跑了 bun test，却漏掉 Cron、ANSI 字符串裁切、测试路径忽略、Windows ARM64 shim 等高价值更新。本文按官方清单做工程化拆解：新增了什么、修了什么、会影响哪里、怎么快速验证，附可执行命令与排错建议。

大家好，我是 iDao。10 年全栈开发，做过架构、运维，也在落地 AI 工程化。这里不搞虚的，只分享能直接跑、能直接用的代码、方案和经验。内容包括：全栈开发实战、系统搭建、可视化大屏、自动化部署、AI 应用、私有化部署等。关注我，一起写能落地的代码，做能上线的项目。

这篇按官方原始更新内容来，不泛讲，直接讲 Bun v1.3.11 到底更新了哪些具体能力。先说结论：这版最大的新增是 Bun.cron 与 Bun.sliceAnsi，此外 bun test 新增路径忽略能力；修复面覆盖 Node 兼容、Web API、install、bundler、CSS、shell、runtime，属于“建议尽快升级并做回归”的版本。

一、安装与版本基线（先确认你在 1.3.11）

a. 问题现象 “我本地好了，CI 还在炸”，大概率是版本不一致。

b. 根因分析 Bun 迭代快，patch 也含行为修复。版本不统一会导致结论失真。

c. 解决步骤

1# 安装
2curl -fsSL https://bun.sh/install | bash
3
4# 升级
5bun upgrade
6
7# 确认
8bun --version
9

d. 验证方式 在本地、CI、容器内分别运行 bun --version，结果都应为 1.3.11。在 CI 中建议把该命令加入构建前一步，确保一致。

二、v1.3.11 新增功能 1：Bun.cron（系统级定时任务）

a. 问题现象 以前要跨平台做定时任务，Linux 用 crontab、macOS 用 launchd、Windows 用 schtasks，维护成本高。

b. 根因分析 各平台调度器接口不统一，Node 层通常只做进程内调度，不是 OS-level。

c. 解决步骤（官方新增 API）

1// 注册系统级 cron：Linux=crontab, macOS=launchd, Windows=Task Scheduler
2await Bun.cron("./worker.ts", "30 2 * * MON", "weekly-report");
3

worker.ts：

1export default {
2  async scheduled(controller) {
3    // controller.cron
4    // controller.scheduledTime
5    await doWork();
6  },
7};
8

解析 cron 表达式：

1const next = Bun.cron.parse("*/15 * * * *");
2const yearly = Bun.cron.parse("@yearly");
3

删除任务：

1await Bun.cron.remove("weekly-report");
2

d. 验证方式

• Linux：视平台不同，一般可在系统日志或 cron 服务日志中查看触发记录，例如 journalctl -u cron 或 journalctl -u crond（取决于发行版）。也可以在 worker.ts 中写入文件到 /tmp 并检查文件写入时间。
• macOS：查看 /tmp 下 bun 相关输出文件，例如 /tmp/bun.cron.<title>.stdout.log 与 .stderr.log，或在 Console.app 搜索任务名。
• Windows：使用 Event Viewer -> Windows Logs -> System 或 Task Scheduler 的历史记录，或让任务写文件到已知目录并验证。

关键参数说明：第三个参数 title 是任务唯一标识；同名重新注册会覆盖已有任务。建议在生产环境先用短周期（每分钟）做 PoC，再转为真实业务频率。

三、v1.3.11 新增功能 2：Bun.sliceAnsi（替代 slice-ansi + cli-truncate）

a. 问题现象 CLI 输出里带颜色码（ANSI）时，普通 slice 会切坏颜色、emoji、组合字符。

b. 根因分析 终端宽度与 JS 字符下标不是一回事，涉及 grapheme cluster 与 East Asian 宽度。

c. 解决步骤

1Bun.sliceAnsi("\x1b[31mhello\x1b[39m", 1, 4); // 保留颜色，输出 ell
2Bun.sliceAnsi("unicorn", 0, 4, "…");          // uni…
3Bun.sliceAnsi("unicorn", -4, undefined, "…"); // …orn
4

还支持 ambiguousIsNarrow 选项（与 Bun.stringWidth / Bun.wrapAnsi 对齐）。

d. 验证方式 构造“颜色 + emoji + 中文 + 超链接”字符串，使用 Bun.sliceAnsi 截断并在终端中展示，确认截断后样式不乱、宽度正确。可用示例：

1const s = "\x1b[32m🔥 中文 🚀\x1b[0m https://example.com";
2console.log(Bun.sliceAnsi(s, 0, 10));
3

在多终端（iTerm / Windows Terminal / Linux console）上对比渲染是否一致。

四、v1.3.11 新增功能 3：Markdown 渲染回调元数据增强

a. 问题现象 以前 listItem 只有 checked（任务列表才有），做嵌套有序列表样式很难。

b. 根因分析 缺少位置与层级信息，无法知道 item 在第几层、第几个。

c. 解决步骤 现在 listItem 可拿到：index / depth / ordered / start / checked。

1const result = Bun.markdown.render("1. first\n   1. sub-a\n2. second", {
2  listItem: (children, { index, depth, ordered, start }) => {
3    const n = (start ?? 1) + index;
4    const marker = ordered ? `${n}.` : "-";
5    return "  ".repeat(depth) + marker + " " + children.trimEnd() + "\n";
6  },
7});
8

d. 验证方式 渲染多层列表，检查一级、二级 marker 是否可定制且正确。对比以前输出，确认新增回调字段能满足自定义格式化需求。

五、v1.3.11 新增功能 4：bun test 支持忽略路径

a. 问题现象 仓库里有 vendor/、fixtures/、submodules/ 时，bun test 会扫描到不该跑的测试。

b. 根因分析 测试发现机制默认递归，未排除目录会造成误跑和性能浪费。

c. 解决步骤bunfig.toml：

1[test]
2pathIgnorePatterns = [
3  "vendor/**",
4  "submodules/**",
5  "fixtures/**",
6  "**/test-data/**"
7]
8

CLI：

1bun test --path-ignore-patterns 'vendor/**' --path-ignore-patterns 'fixtures/**'
2

关键规则：CLI 的 --path-ignore-patterns 会覆盖 bunfig.toml，不是合并。若需长期忽略，优先在 bunfig.toml 中配置并在 CI 中检查生效。

d. 验证方式 在忽略目录放一个故意失败的测试文件，确认不会被发现执行；也可以在 CI 中运行 bun test --list（若支持）或观察测试扫描日志以确认路径过滤生效。

六、重点优化与修复（按影响面）

1. 平台与性能

• Linux x64 包体积减少约 4MB（删除 CMake 相关负担）
• Windows ARM64 下 node_modules/.bin shim 原生化，去掉 x64 模拟开销

1. macOS UDP（dgram）关键修复

• reusePort 在 macOS 可用
• unbound socket send() 自动绑定行为与 Node 对齐
• 修复 setsockopt 失败导致 fd 泄漏与错误信息不透明

1. Node 兼容大规模修复 覆盖 fs / stream / buffer / crypto / process signal / http2 / vm / structuredClone / child_process 等。 典型收益：减少 crash、减少行为偏差、错误码与 Node 更一致。
2. Bun APIs 修复

• Bun.file() 非 ASCII 路径（含德语变音、日文、emoji）编码问题修复
• Bun.Transpiler 对 experimentalDecorators / emitDecoratorMetadata 修复（Angular/NestJS/TypeORM 关键）
• Bun.serve() HTML 引用静态资源 404 修复
• Bun.stringWidth DoS 与 grapheme 边界问题修复
• bun:sql 超参数限制报错改为可读 ERR_POSTGRES_TOO_MANY_PARAMETERS

1. Web API 与安全

• WebSocket 协议校验更严格（Sec-WebSocket-Accept）
• ws.ping()/pong() 空参数行为修复（严格服务端兼容）
• 修复 writeEarlyHints CRLF 注入风险
• HTTP chunked malformed request 防护增强

1. bun install 与 bundler

• 修复大依赖项目 + 安全扫描导致挂起
• 修复代理 + 304 缓存场景下 install 超慢
• 修复 peer 依赖在特定同步加载路径下漏链接
• bundler 修复 bytecode / barrel optimize / dynamic import attributes / compile HTML 路由资源路径等多类问题

常见坑（升级 1.3.11 时高频）

1. bun test 忽略规则没生效：你同时传了 CLI 参数，覆盖了 bunfig 配置。
2. Decorators 项目仍报错：检查 tsconfig 是否同时启用 experimentalDecorators 与 emitDecoratorMetadata。
3. 代理环境 install 仍卡：确认代理变量与 CONNECT 隧道策略，升级后清缓存重试（例如删掉 node_modules、.bun 缓存）。
4. Windows 路径怪异报错：重点回归 fs.realpathSync/readlink/open 相关调用。

快速自检清单

• bun --version = 1.3.11（本地 + CI）
• bun test 已配置 pathIgnorePatterns 并验证生效
• CLI 输出场景已评估 Bun.sliceAnsi 可替换旧包
• 定时任务场景已评估 Bun.cron 跨平台接管可行性
• decorators 框架（Angular/NestJS/TypeORM）已做编译回归
• install、build、runtime、ws、http 关键链路已冒烟

行动建议（今天就能做）

先做两件事： 1）把你项目里 slice-ansi / cli-truncate 替换评估成 Bun.sliceAnsi； 2）把 bun test 的忽略目录配置上，避免无效扫描。

如果你有跨平台定时任务需求，下一步直接 PoC Bun.cron，这是 v1.3.11 最实用的新能力之一。

这次 v1.3.11 的特点很明确：新增 API 可直接落地，修复面覆盖运行时核心路径，且对 Node 兼容继续收敛。对线上项目来说，这类版本的价值很高，建议尽快完成灰度升级与回归。

关注 【iDao技术魔方】，获取更多全栈到AI可落地的实战干货。

《Bun v1.3.11 官方更新全整理：新增功能、关键修复与升级验证》 是转载文章，点击查看原文。