Docker Dockerfile

1. 什么是 Dockerfile

Dockerfile 是一种用于构建 Docker 镜像的文本配置文件，其中逐条记录了构建所需的指令与参数。它通过明确的命令序列，指导 Docker 将应用程序及其运行环境逐层打包，最终生成一个可用的自定义镜像。可以说，Dockerfile 就是构建镜像的“蓝图”或“自动化脚本”。

Dockerfile 文件‌默认没有后缀名‌，纯文本文件，首字母大写，无扩展名，在执行 docker build 命令时，如果未指定文件名，Docker 会自动在当前目录下寻找名为 Dockerfile 的文件进行构建。

如果需要区分不同环境（如开发、测试、生产），可以使用带后缀或特定名称的文件，例如：Dockerfile.dev，使用非默认名称时，必须在构建命令中通过 -f 参数显式指定文件路径：docker build -f Dockerfile.dev -t my-app:dev . 日常开发中，直接创建名为 ‌Dockerfile‌（无后缀）的文件是最标准、最通用的做法。

2. Dockerfile 指令详解表

Dockerfile 中的指令虽然在文件中按顺序书写，但它们的‌执行时机‌和‌作用阶段‌有所不同。为了更清晰地理解，下表按照‌构建与运行时的逻辑执行顺序‌对 Dockerfile 的核心指令进行了汇总和排序：

关键逻辑说明

1. 执行顺序的逻辑性‌：

• 构建时执行‌： FROM, ARG, ENV, WORKDIR, USER, COPY, ADD, RUN, VOLUME, EXPOSE, HEALTHCHECK, STOPSIGNAL, SHELL, ONBUILD 等指令主要在镜像构建阶段处理，确定镜像的静态结构。
• ‌运行时执行‌： ENTRYPOINT 和 CMD 定义的是容器‌启动时‌的行为。ENV 和 USER 既影响构建也影响运行。

2. ‌CMD 与 ENTRYPOINT 的区别：

• CMD: CMD 在docker run 时运行，为启动的容器指定默认要运行的程序，程序运行结束，容器也就结束。CMD 指令指定的程序可被 docker run 命令行参数中指定要运行的程序所覆盖。
• ENTRYPOINT： 类似于 CMD 指令，但其不会被 docker run 的命令行参数指定的指令所覆盖，而且这些命令行参数会被当作参数送给 ENTRYPOINT 指令指定的程序。但是, 如果运行 docker run 时使用了 --entrypoint 选项，将覆盖 ENTRYPOINT 指令指定的程序。如果 Dockerfile 中如果存在多个 ENTRYPOINT 指令，仅最后一个生效。
• 推荐使用组合： ENTRYPOINT "executable" + CMD "param"，这样既固定了主程序，又提供了可覆盖的默认参数。一般是变参才会使用 CMD ，这里的 CMD 等于是在给 ENTRYPOINT 传参
• 同时存在： 如果同时存在 ENTRYPOINT 和 CMD，CMD 的内容会作为参数传递给 ENTRYPOINT。 例如：ENTRYPOINT "echo" 和 CMD "Hello"，容器启动时会执行 echo Hello。

3. ARG 与 ENV 的区别‌：

• ARG 仅在构建时有效，构建完成后消失，适合传递版本号、代理地址等构建期变量。
• ENV 在构建和运行时都有效，适合设置应用运行所需的环境变量（如 NODE_ENV）。

4. ONBUILD 的特殊性‌：

• ONBUILD 指令在当前镜像构建时‌不执行‌，只有当别的 Dockerfile 使用 FROM <当前镜像> 时，这些指令才会在子镜像的构建过程中触发。

5. COPY vs ADD‌：

• 除非需要自动解压 tar 包或从 URL 下载，否则始终使用 COPY，因为它更透明且可预测。

3. 最佳实践与优化技巧

优化 Dockerfile 以提高构建速度，核心在于‌最大化利用 Docker 的层缓存机制‌、‌减小构建上下文体积‌以及‌减少不必要的指令执行‌。以下是经过验证的最佳实践策略：

1. 优化指令顺序以命中缓存‌： Docker 会缓存每一层镜像。如果某一层及其之前的层没有变化，构建时会直接使用缓存。因此，应将变化频率低的内容（如安装依赖）放在前面，变化频率高的内容（如复制源代码）放在后面。 示例：先 COPY package.json 并 RUN npm install，再 COPY . .。这样只要 package.json 不变，依赖安装层就会命中缓存。
2. 合并 RUN 指令以减少层数与开销‌： 虽然现代 Docker 版本对层数限制较宽松，但合并 RUN 指令仍能减小镜像体积并提高构建效率。
3. 使用多阶段构建（Multi-stage Builds）‌： 多阶段构建允许你在一个阶段编译应用，而在另一个阶段仅复制最终产物。这避免了将编译工具链、中间文件和源码带入最终镜像，显著减小镜像体积，从而加快推送和拉取速度。对于编译型语言（如 Go、Java、C++），可以在一个阶段编译代码，在另一个阶段仅复制二进制文件到最小的基础镜像（如 Alpine）中。这能显著减小最终镜像的体积。
4. 减小构建上下文（Build Context）： 在项目根目录创建 .dockerignore 文件，排除不需要复制到镜像中的文件（如 .git、node_modules、日志文件等），以加快构建速度并减小镜像体积。
5. 优先使用 JSON 数组格式‌： 对于 CMD 和 ENTRYPOINT，推荐使用 "executable", "param1" 格式，避免 Shell 形式（/bin/sh -c）带来的信号处理问题和变量扩展意外。
6. ‌并行构建与 BuildKit‌： 确保启用 Docker BuildKit（Docker 18.09+ 默认启用，可通过设置环境变量 DOCKER_BUILDKIT=1 强制开启）。BuildKit 支持并行构建独立层、更高效的缓存管理和更详细的构建输出，能显著提升构建性能。

4. 最佳实践优化示例

基于前文关于 ‌Dockerfile 指令‌、‌构建优化技巧，以下是为 Nuxt 4（基于 Nitro 引擎）生成生产级 Docker 镜像的完整方案。Nuxt 4 通常采用 SSR（服务端渲染）或静态生成，下面分别介绍2种模式下Dockerfile配置。

1. SSR 模式‌下核心 Dockerfile 配置

为了实现最小化镜像体积和最快启动速度，推荐使用 ‌多阶段构建（Multi-stage Builds）‌。

# 阶段 1：构建依赖与编译
FROM node:20-alpine AS builder

# 1. 安装 pnpm (Alpine 镜像默认不含 pnpm)
RUN npm install -g pnpm

WORKDIR /app

# 2. 复制 pnpm 锁文件和 package.json
COPY package.json pnpm-lock.yaml ./

# 3. 安装依赖 (使用 --frozen-lockfile 确保一致性)
RUN pnpm install --frozen-lockfile

# 4. 复制源代码并构建
COPY . .
RUN pnpm run build

# 阶段 2：生产运行环境
FROM node:20-alpine AS runner

# 1. 安装 pnpm (若启动脚本依赖 pnpm，否则可省略，但建议保留以保持一致性)
RUN npm install -g pnpm

WORKDIR /app

ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=3000

# 2. 仅复制构建产物
COPY --from=builder /app/.output ./

EXPOSE 3000

# 3. 启动命令 (Nuxt/Nitro 标准入口)
CMD ["node", "server/index.mjs"]

2. SSG静态模式‌下核心 Dockerfile 配置

在静态模式下，Nuxt 会预渲染所有页面为 HTML/CSS/JS 文件，无需 Node.js 运行时服务器，因此推荐使用 ‌Nginx‌ 作为轻量级 Web 服务器托管这些静态资源。

# 阶段 1：构建静态资源
FROM node:20-alpine AS builder

WORKDIR /app

# 1. 安装 pnpm (若使用 npm/yarn 请调整对应指令)
RUN npm install -g pnpm

# 2. 复制依赖文件并安装
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 3. 复制源码并生成静态文件
COPY . .
# Nuxt 静态生成命令通常为 generate，输出目录默认为 .output/public 或 dist
RUN pnpm run generate

# 阶段 2：Nginx 托管静态文件
FROM nginx:alpine AS runner

# 1. 移除 Nginx 默认配置
RUN rm /etc/nginx/conf.d/default.conf

# 2. 复制自定义 Nginx 配置 (可选，见下方说明)
COPY nginx.conf /etc/nginx/conf.d/default.conf

# 3. 将构建产物复制到 Nginx 默认网页目录
# 注意：Nuxt 4 (Nitro) 静态输出通常在 .output/public
COPY --from=builder /app/.output/public /usr/share/nginx/html

# 4. 暴露 80 端口
EXPOSE 80

# 5. 启动 Nginx
CMD ["nginx", "-g", "daemon off;"]

配套 Nginx 配置 (nginx.conf)，为了确保 SPA（单页应用）或预渲染页面在刷新时不出现 404，建议添加以下 nginx.conf 文件到项目根目录：

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # 启用 Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # 处理 SPA 路由回退：如果文件不存在，返回 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 缓存静态资源
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

3. 构建与运行命令

在项目根目录执行以下命令：

• 构建镜像‌：

docker build -t nuxt4-app:latest .

• ‌运行容器‌：

docker run -d -p 3000:3000 --name my-nuxt-app nuxt4-app:latest

• 验证服务‌

访问 http://localhost:3000 即可看到 Nuxt 应用。

4. 注意事项

务必在项目根目录创建 .dockerignore，排除 node_modules、.git、.nuxt 等无关文件，加速构建上下文传输。

node_modules
.git
.nuxt
.output
dist
*.md
.env