常见报错对照
Bun 高频错误信息的原因与处理路径，按发生阶段分组
| 报错 | 常见原因 | 处理 |
|---|
bun: command not found | ~/.bun/bin 不在 PATH | 重开终端；安装脚本的提示写入 shell 配置后需要重新加载 |
unzip is required to install Bun | Linux 缺少 unzip | sudo apt install unzip（或对应发行版包名）后重跑安装脚本 |
| Windows 上安装后立即报兼容性错误 | 系统低于 Windows 10 1809 | 升级 Windows；无绕过方案 |
| 报错 | 常见原因 | 处理 |
|---|
lockfile had changes, but lockfile is frozen | package.json 与 bun.lock 不同步 | 本地运行 bun install，审查差异后连同 bun.lock 一起提交 |
bun audit 提示缺少锁文件 | 仓库没有 bun.lock | 先 bun install 生成锁文件；audit 依赖锁文件内容 |
bun audit --production 报未知参数 | 该写法不受支持 | 改用 bun audit --prod；monorepo 根目录过滤有已知缺陷 |
安装日志出现 Blocked postinstall | 依赖不在信任列表 | bun pm untrusted 查看；审查后 bun pm trust <pkg> 最小放行 |
Workspace 里 Cannot find package | 新增/移动包后未重新安装 | 在仓库根目录运行 bun install；确认 workspaces 配置覆盖该目录 |
bun update 后 --frozen-lockfile 失败 | 锁文件写入缺陷 | 更新后本地再跑一次 bun install 并提交（见已知问题） |
| 报错 | 常见原因 | 处理 |
|---|
EADDRINUSE / 端口被占用 | 旧进程未退出或端口冲突 | 换掉 PORT，或先结束占用进程；检查 --watch 留下的后台进程 |
error: Script not found "xxx" | 工作目录不对，或脚本名打错 | 确认当前目录的 package.json；bun run 不带参数可列出可用脚本 |
| 读取到旧的/意外的环境变量 | Bun 自动加载了目录里的 .env | 生产环境用 --no-env-file，只保留平台注入的变量 |
Bun.serve 流式响应约 10 秒后被截断 | 默认 idleTimeout 为 10 秒 | 评估后调大 idleTimeout，或对单请求用 server.timeout(req, 0)，并保留应用级总超时 |
| 报错 | 常见原因 | 处理 |
|---|
Cannot find module 'bun:test' 或 Bun 全局类型缺失 | 未安装/未声明 Bun 类型 | bun add -d @types/bun；TypeScript 6 起需在 tsconfig.json 显式写 "types": ["bun"] |
--isolate 下动态 import 顶层 await 模块失败 | 1.3.14 的已知回归 | 受影响套件暂时串行运行；跟踪已知问题 |
测试在 --parallel 下互相干扰 | 共享端口、数据库或临时目录 | 用 BUN_TEST_WORKER_ID 分配每 Worker 独立资源，或让该组保持串行 |
bun --version 确认版本，再查版本特性矩阵排除“版本不够”。- 确认工作目录与实际生效的
package.json、bunfig.toml。
- 用最小复现区分项目配置问题与 Bun 运行时问题。
- 查已知问题与 oven-sh/bun issues，再决定升级或规避。
Bun Docs