> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 欢迎使用 Bun

> Bun 是一个用于开发现代 JavaScript/TypeScript 应用的一体化工具包。

<CardGroup>
  <Card
    icon="cog"
    title="Bun 运行时"
    href="/runtime"
    cta={
  <span>
    通过 <code>bun run</code> 开始使用
  </span>
}
  >
    一个快速的 JavaScript 运行时，设计为 Node.js 的替代品
  </Card>

  <Card
    icon="box"
    title="Bun 包管理器"
    href="/pm/cli/install"
    cta={
  <span>
    通过 <code>bun install</code> 开始使用
  </span>
}
  >
    利用全局缓存和工作区，安装包速度比 npm 快30倍
  </Card>

  <Card
    icon="flask-conical"
    title="Bun 测试运行器"
    href="/test"
    cta={
  <span>
    通过 <code>bun test</code> 开始使用
  </span>
}
  >
    与 Jest 兼容，TypeScript 优先支持快照、DOM 和监听模式的测试
  </Card>

  <Card
    icon="combine"
    title="Bun 打包器"
    href="/bundler"
    cta={
  <span>
    通过 <code>bun build</code> 开始使用
  </span>
}
  >
    为浏览器和服务器打包 TypeScript、JSX、React 和 CSS
  </Card>
</CardGroup>

***

## 入门指南

Bun 作为一个单一的、无依赖的二进制文件提供，包含运行时、包管理器、测试运行器和打包器。您是 Bun 新手吗？

<CardGroup>
  <Card icon="download" title="安装 Bun" href="/installation">
    支持的平台及所有安装方法。
  </Card>

  <Card icon="zap" title="快速开始" href="/quickstart">
    使用 Bun.serve 在几分钟内创建 Hello world。
  </Card>
</CardGroup>

***

## 内部组成

* 运行时：几乎无开销地执行 JavaScript/TypeScript 文件和包脚本。
* 包管理器：使用 `bun install` 实现快速安装、工作区、覆盖和审计。
* 测试运行器：支持 Jest，TypeScript 优先，含快照、DOM 和监听模式。
* 打包器：支持 JS/TS/JSX 的原生打包，含代码拆分、插件和 HTML 导入。

通过上方卡片探索每个模块。每个章节包括概览、快速示例、参考文档及最佳实践，方便快速浏览和深入学习。

***

## 什么是 Bun？

Bun 是一个面向 JavaScript 和 TypeScript 应用的一体化工具包。它以名为 `bun` 的单个可执行文件提供。

其核心是 *Bun 运行时*，这是一个快速的 JavaScript 运行时，设计为 **Node.js 的替代品**。它使用 Zig 语言编写，底层由 JavaScriptCore 驱动，大幅减少启动时间和内存使用。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run index.tsx  # 原生支持 TS 和 JSX
```

`bun` 命令行工具还实现了测试运行器、脚本执行器以及兼容 Node.js 的包管理器，速度远超现有工具，并且几乎无需改动即可用于现有 Node.js 项目。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run start                 # 运行 `start` 脚本
bun install <pkg>             # 安装一个包
bun build ./index.tsx         # 打包浏览器项目
bun test                      # 运行测试
bunx cowsay 'Hello, world!'   # 执行一个包
```

## 什么是运行时？

JavaScript（更正式地说是 ECMAScript）只是编程语言的一个 *规范*。任何人都可以写一个 JavaScript *引擎*，输入有效的 JavaScript 程序并执行它。当前最流行的两个引擎是 V8（Google 研发）和 JavaScriptCore（Apple 研发），二者都是开源的。

但是大多数 JavaScript 程序不会在真空中运行。它们需要访问外部世界以完成有用任务。这时就需要 *运行时*。运行时实现了额外的 API，供执行的 JavaScript 程序使用。

### 浏览器

浏览器内置了 JavaScript 运行时，提供了一组与 Web 相关的 API，通过全局对象 `window` 暴露。浏览器执行的任何 JavaScript 代码都可以使用这些 API，在当前网页环境中实现交互或动态行为。

### Node.js

同样，Node.js 是用于非浏览器环境（如服务器）的 JavaScript 运行时。Node.js 执行的程序可以访问一组 Node.js 特有的 [全局变量](https://nodejs.org/api/globals.html)，如 `Buffer`、`process` 和 `__dirname`，并内置了用于操作操作系统任务（例如读写文件(`node:fs`)和网络通信(`node:net`、`node:http`)）的模块。Node.js 还实现了一个基于 CommonJS 的模块系统和解析算法，这是 JavaScript 原生模块系统之前的标准。

Bun 被设计为 Node.js 的更快速、更精简、更现代化的替代品。

## 设计目标

Bun 从零开始设计，充分考虑当今的 JavaScript 生态系统。

* **速度**。Bun 进程启动速度目前比 Node.js 快 [4 倍](https://twitter.com/jarredsumner/status/1499225725492076544)（不妨亲自试试！）
* **TypeScript 和 JSX 支持**。您可以直接执行 `.jsx`、`.ts` 和 `.tsx` 文件；Bun 的转译器会在执行前将它们转换为原生 JavaScript。
* **ESM 和 CommonJS 兼容性**。世界正在转向 ES 模块（ESM），但 npm 上数以百万计的包仍然需要 CommonJS。Bun 推荐使用 ES 模块，但也支持 CommonJS。
* **Web 标准 API**。Bun 实现了诸如 `fetch`、`WebSocket` 和 `ReadableStream` 等标准 Web API。Bun 由 JavaScriptCore 引擎驱动，该引擎由 Apple 为 Safari 开发，因此像 [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) 和 [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) 这样的 API 直接使用了 [Safari 的实现](https://github.com/oven-sh/bun/blob/HEAD/src/jsc/bindings/webcore/JSFetchHeaders.cpp)。
* **Node.js 兼容性**。除了支持 Node 风格的模块解析外，Bun 还旨在与内置的 Node.js 全局对象（`process`、`Buffer`）和模块（`path`、`fs`、`http` 等）完全兼容。*这项工作仍在进行中，尚未完成。* 请参阅 [兼容性页面](/runtime/nodejs-compat) 了解当前状态。

Bun 不仅是一个运行时。长期目标是成为一个统一的基础设施工具包，用于构建 JavaScript/TypeScript 应用，涵盖包管理器、转译器、打包器、脚本执行器、测试运行器等多方面功能。