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. 解决步骤

bash 复制代码

# 安装
curl -fsSL https://bun.sh/install | bash

# 升级
bun upgrade

# 确认
bun --version

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）

ts 复制代码

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

worker.ts：

ts 复制代码

export default {
  async scheduled(controller) {
    // controller.cron
    // controller.scheduledTime
    await doWork();
  },
};

解析 cron 表达式：

ts 复制代码

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

删除任务：

ts 复制代码

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

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. 解决步骤

ts 复制代码

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

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

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

ts 复制代码

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

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

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

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

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

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

ts 复制代码

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

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

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

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

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

c. 解决步骤 bunfig.toml：

toml 复制代码

[test]
pathIgnorePatterns = [
  "vendor/**",
  "submodules/**",
  "fixtures/**",
  "**/test-data/**"
]

CLI：

bash 复制代码

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

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

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

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

平台与性能

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

macOS UDP（dgram）关键修复

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

Node 兼容大规模修复覆盖 fs / stream / buffer / crypto / process signal / http2 / vm / structuredClone / child_process 等。典型收益：减少 crash、减少行为偏差、错误码与 Node 更一致。
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

Web API 与安全

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

bun install 与 bundler

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

常见坑（升级 1.3.11 时高频）

bun test 忽略规则没生效：你同时传了 CLI 参数，覆盖了 bunfig 配置。
Decorators 项目仍报错：检查 tsconfig 是否同时启用 experimentalDecorators 与 emitDecoratorMetadata。
代理环境 install 仍卡：确认代理变量与 CONNECT 隧道策略，升级后清缓存重试（例如删掉 node_modules、.bun 缓存）。
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可落地的实战干货。