在 Bun 运行时中运行、监听、热重载…

适用于使用 Bun runtime 运行脚本、配置 bunfig.toml/env、watch/hot、preload、workspaces 和调试的日常开发场景。

适用场景

解决思路

1. 在 Linux 上选择 Bun 运行时，以基于 JavaScriptCore（Safari 引擎）获得比 Node.js 约 4x 更快的启动。
2. 运行文件：`bun run index.ts`；也可简写为 `bun index.ts`。
3. 以 watch 模式运行文件：`bun --watch run index.ts`。
4. 运行 package.json 脚本：`bun run dev`。
5. 以热重载运行：`bun --hot run server.ts`。
6. 使用 `--watch`：在文件变化时重启进程。
7. 使用 `--hot`：进行热模块替换并保留状态。
8. 使用 `--smol`：降低内存占用（GC 会更慢）。
9. 使用 `--inspect`：启用调试器。
10. 使用 `--preload`：在执行前加载模块。
11. 使用 `--env-file`：加载指定 `.env` 文件。
12. 使用 `-e, --eval`：执行代码字符串。
13. 运行 JavaScript 文件：`bun run index.js`。
14. 运行 TypeScript 文件：`bun run index.ts`。
15. 运行 JSX 文件：`bun run index.jsx`。
16. 运行 TSX 文件：`bun run index.tsx`；Bun 会即时转译 TypeScript 和 JSX。
17. 将 Bun flags 紧跟 `bun` 后：正确写法 `bun --watch run dev`；错误写法 `bun run dev --watch`（flag 会传给脚本）。
18. 运行 package.json 脚本：`bun run dev`。
19. 若无 Bun 命令冲突，使用简写：`bun dev`。
20. 列出可用脚本：`bun run`。
21. 用 Bun 替代 Node 运行脚本：`bun run --bun vite`。
22. 使用 lifecycle hooks：Bun 会尊重 `preclean`、`postclean` 等。
23. Watch 模式：用 `--watch` 在变更时完整重启进程，例如 `bun --watch run server.ts`。
24. Hot reloading：用 `--hot` 替换模块并保留连接/状态，例如 `bun --hot run server.ts`。
25. 自动加载 `.env` 文件：直接 `bun run index.ts`，会加载 `.env`、`.env.local`、`.env.development`。
26. 指定 env 文件：`bun --env-file .env.production run index.ts`。
27. 禁用自动加载：在 `bunfig.toml` 中设置 `env = false`。
28. 在代码中访问环境变量：`const apiKey = process.env.API_KEY;`。
29. 在代码中访问 Bun 环境变量：`const bunEnv = Bun.env.NODE_ENV;`。
30. 直接使用 `Bun` 全局作为主 API 对象。
31. 直接使用 `Buffer` 全局处理二进制数据（来自 Node.js）。
32. 直接使用 `process` 全局获取进程信息（来自 Node.js）。
33. 直接使用 `fetch` 全局发起 HTTP 请求（来自 Web）。
34. 直接使用 `Request/Response` 全局处理 HTTP 类型（来自 Web）。
35. 直接使用 `WebSocket` 全局作为 WebSocket 客户端（来自 Web）。
36. 直接使用 `crypto` 全局进行加密（来自 Web）。
37. 直接使用 `console` 全局进行日志（来自 Web）。
38. 直接使用 `__dirname` 获取当前目录（来自 Node.js）。
39. 直接使用 `__filename` 获取当前文件（来自 Node.js）。
40. 预加载模块：`bun --preload ./setup.ts run index.ts`。
41. 在 `bunfig.toml` 中配置预加载：`preload = ["./setup.ts"]`。
42. 将预加载用于 polyfills、全局 setup、instrumentation。
43. 从 stdin 执行：`echo "console.log('Hello')" | bun run -`。
44. 从文件重定向到 stdin 执行：`bun run - < script.js`。
45. 在 monorepo 中按过滤运行脚本：`bun run --filter 'pkg-*' build`。
46. 在所有 workspaces 中运行：`bun run --filter '*' test`。
47. 启动调试器：`bun --inspect run index.ts`。
48. 等待调试器连接：`bun --inspect-wait run index.ts`。
49. 在首行断点：`bun --inspect-brk run index.ts`。
50. 通过 Chrome DevTools 或 VS Code 连接调试器。
51. 修复 `Cannot find module`：运行 `bun install`。
52. 修复 `Top-level await`：将代码包在 async 函数中，或使用 `.mts`。
53. 修复 `--watch not working`：将 flag 放在 `run` 前。
54. 需要配置 bunfig.toml、测试配置、包管理器行为、JSX 选项时，加载 `references/bunfig.md`。
55. 需要完整 CLI flag 参考、高级 runtime 选项、调试配置时，加载 `references/cli-flags.md`。
56. 排查 import 错误、配置路径别名、理解 Bun 解析算法时，加载 `references/module-resolution.md`。

适用边界 · 注意事项

• 未安装 Bun 运行时或无法在目标环境使用 Bun 时不适用。
• 必须严格依赖 Node.js 运行时行为且未验证 Bun 兼容性时不适用。
• 目标部署平台不支持 JavaScriptCore/Bun 时不适用。