一、 Dockerfile 指令全参数详解

Dockerfile 是定义镜像“静态环境”的说明书。

二、 核心进阶逻辑：多阶段构建 (Multi-stage)

在企业级 Node.js 开发中，为了解决“镜像臃肿”问题，通常采用双阶段设计：

1. 逻辑结构图

• 阶段一：Builder（施工房）：安装编译器、源代码、缓存。任务是把代码编译成 dist。

• 阶段二：Runner（精装房）：重新开一个干净的镜像，只通过 COPY --from=builder 把 dist 拿过来。

2. 代码演练：利用“层缓存”优化速度

# --- 第一阶段：编译 ---
FROM node:20-slim AS builder
WORKDIR /app

# 【关键】将 package.json 拷贝放在前面。
# 只要这个文件没变，Docker 就不会重新跑耗时的 install，直接复用缓存层。
COPY package.json pnpm-lock.yaml ./
RUN pnpm install

COPY . .
RUN pnpm build

# 

三、 Dockerfile vs. Docker Compose：元件与组装

1. 深度解读：两者的关联性

• 关联性：在 docker-compose.yml 中使用 build: . 即可直接触发 Dockerfile 的构建流程，实现“一键代码到系统”。

• 网络互通（服务发现）：Compose 会自动创建内部局域网。容器连接数据库时，主机名直接填 服务名（Service Name）（如 db），Compose 的内置 DNS 会自动解析 IP。

• 动静结合：Dockerfile 负责固化环境（静），Compose 负责动态挂载目录、配置网络、管理端口（动）。

2. 代码联动示例

# docker-compose.yml
version: '3'
services:
  web-app:
    build: .             # 关联 Dockerfile
    container_name: web_service
    ports:
      - "8080:3000"      

四、 避坑指南与最佳实践（金句总结）

1.  陷阱：

   • 如果 Dockerfile 需要 COPY dist/，绝对不能在 .dockerignore 里忽略 dist/。否则 Docker 引擎会因找不到文件而报错。

2. 镜像即光盘：

   • Dockerfile 做出来的镜像是“死”的只读光盘（ROM）；启动后的容器才是“活”的运行环境。

3. 动静分离的思想：

   • 死的东西（入镜像）：代码逻辑、Node 库、编译成品。

   • 活的东西（入卷）：数据库文件、用户上传图片、日志、配置文件。不要把活数据存在镜像里！

4. 变量管理：

   • GitLab CI 自带的 $CI_... 变量是系统自动注入的（如仓库地址、分支名）；而 $SONAR_TOKEN 类变量需在 Settings 界面手动录入。

5. 命令顺序：

   • 顺序决定速度：修改代码频繁，修改依赖不频繁。因此先 COPY package.json 再 COPY 源码，能极大加速构建。

6. 安全原则：

   • 默认容器是 root 权限。生产环境建议在 Dockerfile 最后使用 USER node 切换用户，降低被攻破后的风险。

💡 总结：Dockerfile 保证了环境的确定性，Docker Compose 保证了系统的协作性。掌握了卷（Volume）的挂载和多阶段构建的隔离，你就掌握了 Docker 生产级应用的核心。