> ## 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.

# 使用 Docker 容器化 Bun 应用程序

<Note>
  本指南假设您已安装了 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。
</Note>

[Docker](https://www.docker.com) 是一个将应用程序打包并运行于轻量、便携的\_容器\_中的平台，容器封装了所有必要的依赖。

***

要对我们的应用进行\_容器化\_，我们需要定义一个 `Dockerfile`。该文件包含初始化容器、复制本地项目文件、安装依赖并启动应用的一系列指令。

```docker Dockerfile icon="docker" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 使用官方的 Bun 镜像
# 所有版本见 https://hub.docker.com/r/oven/bun/tags
FROM oven/bun:1 AS base
WORKDIR /usr/src/app

# 在临时目录安装依赖
# 这样可缓存依赖，提升后续构建速度
FROM base AS install
RUN mkdir -p /temp/dev
COPY package.json bun.lock /temp/dev/
RUN cd /temp/dev && bun install --frozen-lockfile

# 使用 --production 安装（排除 devDependencies）
RUN mkdir -p /temp/prod
COPY package.json bun.lock /temp/prod/
RUN cd /temp/prod && bun install --frozen-lockfile --production

# 从临时目录复制 node_modules
# 然后将所有（未被忽略的）项目文件复制到镜像
FROM base AS prerelease
COPY --from=install /temp/dev/node_modules node_modules
COPY . .

# [可选] 测试 & 构建
ENV NODE_ENV=production
RUN bun test
RUN bun run build

# 将生产依赖和源代码复制到最终镜像
FROM base AS release
COPY --from=install /temp/prod/node_modules node_modules
COPY --from=prerelease /usr/src/app/index.ts .
COPY --from=prerelease /usr/src/app/package.json .

# 运行应用
USER bun
EXPOSE 3000/tcp
ENTRYPOINT [ "bun", "run", "index.ts" ]
```

***

现在您有了 Docker 镜像，我们来了解 `.dockerignore`，它的语法与 `.gitignore` 相同，这里您需要指定不应出现在 Docker 构建任一阶段的文件/目录。一个忽略文件示例如下：

```txt .dockerignore icon="docker" theme={"theme":{"light":"github-light","dark":"dracula"}}
node_modules
Dockerfile*
docker-compose*
.dockerignore
.git
.gitignore
README.md
LICENSE
.vscode
Makefile
helm-charts
.env
.editorconfig
.idea
coverage*
```

***

接着我们用 `docker build` 将此 `Dockerfile` 转换为一个\_Docker 镜像\_，即一个包含应用运行所需全部依赖和配置的自包含模板。

`-t` 参数允许我们为镜像命名，`--pull` 告诉 Docker 自动下载基础镜像（`oven/bun`）的最新版本。第一次构建会较慢，因为需要下载所有基础镜像和依赖。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
docker build --pull -t bun-hello-world .
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
[+] Building 0.9s (21/21) FINISHED
 => [internal] load build definition from Dockerfile                                                                                     0.0s
 => => transferring dockerfile: 37B                                                                                                      0.0s
 => [internal] load .dockerignore                                                                                                        0.0s
 => => transferring context: 35B                                                                                                         0.0s
 => [internal] load metadata for docker.io/oven/bun:1                                                                                    0.8s
 => [auth] oven/bun:pull token for registry-1.docker.io                                                                                  0.0s
 => [base 1/2] FROM docker.io/oven/bun:1@sha256:373265748d3cd3624cb3f3ee6004f45b1fc3edbd07a622aeeec17566d2756997                         0.0s
 => [internal] load build context                                                                                                        0.0s
 => => transferring context: 155B                                                                                                        0.0s
 # ...大量命令...
 => exporting to image                                                                                                                   0.0s
 => => exporting layers                                                                                                                  0.0s
 => => writing image sha256:360663f7fdcd6f11e8e94761d5592e2e4dfc8d167f034f15cd5a863d5dc093c4                                             0.0s
 => => naming to docker.io/library/bun-hello-world                                                                                       0.0s
```

***

我们已经构建了一个新的\_Docker 镜像\_。现在用该镜像启动一个真正运行的\_容器\_。

使用 `docker run` 开启一个新容器，基于 `bun-hello-world` 镜像。容器将以\_后台\_模式 (`-d`) 运行，并将容器的 3000 端口映射到本地机器的 3000 端口 (`-p 3000:3000`)。

`run` 命令输出一个代表\_容器 ID\_的字符串。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
docker run -d -p 3000:3000 bun-hello-world
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d
```

***

容器现已在后台运行。访问 [localhost:3000](http://localhost:3000) 应能看到 `Hello, World!` 消息。

***

要停止容器，使用 `docker stop <container-id>`。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
docker stop 7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d
```

***

若找不到容器 ID，可以用 `docker ps` 列出所有运行中的容器。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
docker ps
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
7f03e212a15e        bun-hello-world     "bun run index.ts"       2 minutes ago       Up 2 minutes        0.0.0.0:3000->3000/tcp   flamboyant_cerf
```

***

就这样！更多高级用法请参考 [Docker 文档](https://docs.docker.com/)。