bun create 命令详解

INFO

使用 Bun 并不一定需要 bun create 命令。实际上，Bun 不需要任何配置就能工作。这个命令的存在只是为了让你的开始过程更快捷、更简单。

什么是 bun create？

bun create 是一个灵活的命令，用于快速创建新的 Bun 项目。它可以从多种不同的源创建项目：

从单个 React 组件文件创建完整项目
从 npm 上的 create-<模板名> 包创建项目
从 GitHub 仓库创建项目
从本地模板创建项目

如果你想创建一个全新的空白项目，建议使用 `bun init` 命令。

从 React 组件创建项目

Bun 提供了一个令人惊叹的功能：只需一个命令，就能将单个 React 组件转变为一个完整的开发环境！

bash

$ bun create ./MyComponent.jsx  # 同样支持 .tsx 文件

这个命令会自动创建一个带有热重载和生产构建功能的完整项目。

提示 🚀 Create React App 的继任者 — bun create <组件> 提供了开发者喜爱的 Create React App 的所有功能，但采用了现代工具链，构建更快，并支持后端开发。

工作原理图解

当你运行 bun create <组件> 时，Bun 会执行以下步骤：

txt

+------------------+
| 分析模块依赖     |  <-- 开始步骤
+------------------+
         |
         v
+------------------+
| 收集运行组件所需的依赖
+------------------+
         |
         v
+------------------+
| 扫描入口点导出的React组件
+------------------+
         |
         v
+------------------+
| 生成包含依赖和脚本的package.json
+------------------+
         |
         v
+------------------+
| 安装缺失依赖     |
+------------------+
         |
         v
+------------------+
| 生成必要文件     |
+------------------+
         |
         v
+------------------+
| 启动前端开发服务器    |  <-- 结束步骤
+------------------+

在这个过程中，Bun 会生成以下文件：

${component}.html（HTML 入口文件）
${component}.client.tsx（前端入口点）
${component}.css（CSS 样式文件）

这提供了一个完整的开发环境，你可以立即开始工作！

与 TailwindCSS 搭配使用

TailwindCSS 是一个极其流行的实用优先的 CSS 框架，用于给 Web 应用添加样式。

当你运行 bun create <组件> 时，Bun 会自动扫描你的 JSX/TSX 文件中的 TailwindCSS 类名（以及它导入的任何文件）。如果检测到 TailwindCSS 类名，它会自动添加以下依赖到你的 package.json 中：

json

{
  "dependencies": {
    "tailwindcss": "^4",
    "bun-plugin-tailwind": "latest"
  }
}

同时，Bun 还会配置 bunfig.toml 文件，使 Bun.serve() 使用 TailwindCSS 插件：

toml

[serve.static]
plugins = ["bun-plugin-tailwind"]

还会创建一个在顶部包含 @import "tailwindcss"; 的 ${component}.css 文件：

css

@import "tailwindcss";

与 shadcn/ui 搭配使用

shadcn/ui 是一个非常流行的用于构建 Web 应用的组件库工具。

bun create <组件> 会扫描从 @/components/ui 导入的任何 shadcn/ui 组件。如果找到任何组件，它会运行：

bash

# 假设 bun 检测到导入了 @/components/ui/accordion 和 @/components/ui/button
$ bunx shadcn@canary add accordion button # 以及其他任何组件

由于 shadcn/ui 本身使用 TailwindCSS，bun create 也会添加必要的 TailwindCSS 依赖到你的 package.json 中，并配置 bunfig.toml 以在 Bun.serve() 中使用 TailwindCSS 插件。

此外，Bun 还会设置以下内容：

tsconfig.json，将 "@/*" 别名设置为指向 "src/*" 或 .（取决于是否存在 src/ 目录）
components.json，让 shadcn/ui 知道这是一个 shadcn/ui 项目
styles/globals.css 文件，按照 shadcn/ui 期望的方式配置 Tailwind v4
${component}.build.ts 文件，使用配置好的 bun-plugin-tailwind 为生产环境构建组件

> `bun create ./MyComponent.jsx` 是在本地运行 [Claude](https://claude.ai) 或 ChatGPT 等 LLM 生成代码的最简单方法之一。

从 npm 创建项目

$ bun create <模板名> [<目标目录>]

假设你没有同名的本地模板，此命令将从 npm 下载并执行 create-<模板名> 包。以下两个命令的行为完全相同：

$ bun create remix
$ bunx create-remix

有关完整文档和使用说明，请参阅相关 create-<模板名> 包的文档。

从 GitHub 创建项目

这将下载 GitHub 仓库的内容到本地磁盘。

bash

$ bun create <用户>/<仓库>
$ bun create github.com/<用户>/<仓库>

你可以为目标文件夹指定名称。如果没有指定目标，将使用仓库名作为文件夹名：

bash

$ bun create <用户>/<仓库> mydir
$ bun create github.com/<用户>/<仓库> mydir

Bun 将执行以下步骤：

txt

+-----------------+
| 下载模板        |  <-- 开始步骤
+-----------------+
        |
        v
+-----------------+
| 将模板文件复制  |
| 到目标文件夹    |
+-----------------+
        |
        v
+-----------------+
| 使用bun install |
| 安装依赖        |
+-----------------+
        |
        v
+-----------------+
| 初始化Git仓库   |
+-----------------+
        |
        v
+-----------------+
| 运行模板配置的  |  <-- 结束步骤
| start脚本       |
+-----------------+

WARNING

默认情况下，Bun 不会覆盖任何现有文件。如果需要覆盖现有文件，请使用 --force 标志。

从本地模板创建项目

DANGER

警告与远程模板不同，使用本地模板运行 bun create 将删除目标文件夹（如果已存在）！请小心使用。

Bun 的模板系统可以扩展以支持在本地文件系统中定义的自定义模板。这些模板应该位于以下目录之一：

$HOME/.bun-create/<名称>：全局模板
<项目根目录>/.bun-create/<名称>：项目特定模板

提示你可以通过设置 BUN_CREATE_DIR 环境变量来自定义全局模板路径。

创建本地模板的步骤

导航到 $HOME/.bun-create 目录
创建一个新目录，使用你想要的模板名称
创建必要的文件

bash

$ cd $HOME/.bun-create
$ mkdir foo
$ cd foo

然后，在该目录中创建一个 package.json 文件，内容如下：

json

{
  "name": "foo"
}

你可以在文件系统的其他位置运行 bun create foo 来验证 Bun 是否正确找到了你的本地模板。

设置逻辑

你可以在本地模板的 package.json 的 "bun-create" 部分中指定安装前和安装后的设置脚本。

json

{
  "name": "@bun-examples/simplereact",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "bun-create": {
    "preinstall": "echo '开始安装...'", // 单个命令
    "postinstall": ["echo '完成！'"], // 命令数组
    "start": "bun run echo '你好，世界！'"
  }
}

支持以下字段。每个字段可以对应一个字符串或字符串数组。命令数组将按顺序执行。

字段	描述
`postinstall`	在安装依赖之后运行
`preinstall`	在安装依赖之前运行

克隆模板后，bun create 会在将 package.json 写入目标文件夹之前，自动删除其中的 "bun-create" 部分。

命令参考

命令行标志

标志	描述
`--force`	覆盖现有文件
`--no-install`	跳过安装 `node_modules` 和任务
`--no-git`	不初始化 git 仓库
`--open`	完成后启动并在浏览器中打开

环境变量

名称	描述
`GITHUB_API_DOMAIN`	如果你使用的是 GitHub 企业版或代理，可以自定义 Bun 下载时使用的 GitHub 域名
`GITHUB_TOKEN` (或 `GITHUB_ACCESS_TOKEN`)	这允许 `bun create` 处理私有仓库或在你被限制速率时工作。如果两者都存在，会优先选择 `GITHUB_TOKEN`

bun create 的详细工作原理当你运行 bun create ${template} ${destination} 时，会发生以下情况：

如果是远程模板：

获取 registry.npmjs.org/@bun-examples/${template}/latest 并解析
获取 registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz
解压并提取 ${template}-${latestVersion}.tgz 到 ${destination}
- 如果有会覆盖的文件，警告并退出，除非传递了 --force

如果是 GitHub 仓库：

从 GitHub API 下载 tarball
解压并提取到 ${destination}
- 如果有会覆盖的文件，警告并退出，除非传递了 --force

否则，如果是本地模板：

打开本地模板文件夹
递归删除目标目录
使用最快的系统调用递归复制文件（在 macOS 上是 fcopyfile，在 Linux 上是 copy_file_range）。不复制或遍历 node_modules 文件夹（这一点就比 cp 快）
解析 package.json，更新 name 为 ${basename(destination)}，删除 package.json 中的 bun-create 部分并将更新后的 package.json 保存到磁盘。
- 如果检测到 Next.js，将 bun-framework-next 添加到依赖列表中
- 如果检测到 Create React App，将 /src/index.{js,jsx,ts,tsx} 中的入口点添加到 public/index.html
- 如果检测到 Relay，添加 bun-macro-relay 以使 Relay 工作
自动检测 npm 客户端，优先选择 pnpm，其次是 yarn（v1），最后是 npm
使用 npm 客户端运行 "bun-create": { "preinstall" } 中定义的任务
运行 ${npmClient} install，除非传递了 --no-install 或 package.json 中没有依赖项
使用 npm 客户端运行 "bun-create": { "postinstall" } 中定义的任务
运行 git init; git add -A .; git commit -am "Initial Commit";
- 将 gitignore 重命名为 .gitignore。NPM 会自动阻止 .gitignore 文件出现在包中。
- 如果有依赖项，这会在单独的线程中并行运行，同时安装 node_modules
- 经测试，使用 libgit2（如果可用）在微基准测试中速度慢了 3 倍 :::

实际应用场景

场景一：从 React 组件快速创建项目

假设你有一个设计好的 React 组件 ProductCard.tsx，想要围绕它构建一个完整的产品展示应用：

bash

$ bun create ./ProductCard.tsx

Bun 会自动创建一个完整的项目，包括所有必要的依赖和配置。

场景二：基于热门框架创建项目

想要创建一个基于流行框架的新项目：

bash

$ bun create react my-awesome-app
$ cd my-awesome-app
$ bun dev  # 启动开发服务器

场景三：创建自定义本地模板

如果你经常创建具有特定结构的项目，可以创建自己的本地模板：

bash

$ mkdir -p $HOME/.bun-create/my-template
$ cd $HOME/.bun-create/my-template

添加模板文件，包括 package.json：

json

{
  "name": "my-template",
  "version": "1.0.0",
  "bun-create": {
    "postinstall": "echo '项目创建成功！'"
  },
  "dependencies": {
    "express": "^4.17.1"
  }
}

使用模板：

bash

$ bun create my-template ~/projects/new-project

小结

bun create 命令提供了一种灵活高效的方式来创建新的 Bun 项目。无论你是想从单个 React 组件构建、使用流行的 npm 模板、从 GitHub 仓库克隆，还是使用自定义的本地模板，bun create 都能满足你的需求。

特别是其从单个 React 组件创建完整项目的能力，使其成为快速原型设计和测试 AI 生成代码的绝佳工具。对于初创项目或概念验证而言，这是一个巨大的生产力提升。

虽然 `bun create` 让项目创建变得简单，但在生产环境中，请确保你了解生成的项目结构和配置，以便根据你的特定需求进行调整。

bun create 命令详解 ​

什么是 bun create？ ​

从 React 组件创建项目 ​

工作原理图解 ​

与 TailwindCSS 搭配使用 ​

与 shadcn/ui 搭配使用 ​

从 npm 创建项目 ​

从 GitHub 创建项目 ​

从本地模板创建项目 ​

创建本地模板的步骤 ​

设置逻辑 ​

命令参考 ​

命令行标志 ​

环境变量 ​

实际应用场景 ​

场景一：从 React 组件快速创建项目 ​

场景二：基于热门框架创建项目 ​

场景三：创建自定义本地模板 ​

小结 ​

bun create 命令详解

什么是 bun create？

从 React 组件创建项目

工作原理图解

与 TailwindCSS 搭配使用

与 shadcn/ui 搭配使用

从 npm 创建项目

从 GitHub 创建项目

从本地模板创建项目

创建本地模板的步骤

设置逻辑

命令参考

命令行标志

环境变量

实际应用场景

场景一：从 React 组件快速创建项目

场景二：基于热门框架创建项目

场景三：创建自定义本地模板

小结