Dockerfile 最佳实践

编写高效、安全、可维护的 Dockerfile

.dockerignore 模板 1/6

排除不需要的文件，减小构建上下文，加速构建并避免泄露敏感信息。

# Node.js .dockerignore
node_modules
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.npm
.yarn
dist
build
.env
.env.local
.env.*.local
.git
.gitignore
.vscode
.idea
*.md
!README.md
Dockerfile
docker-compose*.yml
.dockerignore
coverage
.nyc_output
# Python .dockerignore
__pycache__
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
.venv/
.env
*.egg-info/
dist/
build/
.git
.gitignore
.vscode
.idea
*.md
!README.md
Dockerfile
docker-compose*.yml
.dockerignore
.pytest_cache
.mypy_cache
.coverage
htmlcov/
# Java .dockerignore
target/
!.mvn/wrapper/maven-wrapper.jar
*.class
*.jar
*.war
*.ear
.git
.gitignore
.vscode
.idea
*.iml
*.md
!README.md
Dockerfile
docker-compose*.yml
.dockerignore
.mvn/wrapper
.mvn/timing
build/
out/
.gradle/

层缓存优化 2/6

合理利用 Docker 层缓存，让构建只重跑变化的部分。

利用 --build-arg 传递构建参数

ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-alpine

# 先复制依赖文件，利用缓存
COPY package.json package-lock.json ./
RUN npm ci --production

# 再复制源码（源码变化不影响依赖层缓存）
COPY . .
CMD ["node", "server.js"]

利用 --target 多阶段命名

# 阶段1：构建
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 阶段2：运行
FROM nginx:alpine AS runtime
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
# 只构建到 builder 阶段（调试用）
docker build --target builder -t myapp:builder .

# 构建最终运行镜像
docker build -t myapp:latest .
💡 关键原则：变化频率低的指令放前面（系统依赖安装），变化频率高的放后面（源码复制）。

ENTRYPOINT vs CMD 3/6

维度ENTRYPOINTCMD
用途定义容器主命令（不可被覆盖）定义默认参数（可被覆盖）
docker run 覆盖需 --entrypoint 才能覆盖直接在命令后追加即覆盖
典型场景固定执行某个程序提供默认启动命令
搭配使用ENTRYPOINT 定义命令 + CMD 定义默认参数

搭配用法

ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8080"]

# 默认执行: python app.py --port 8080
# 覆盖参数: docker run myapp --port 3000
# 执行: python app.py --port 3000
⚠️ 推荐使用 exec 格式 ["executable", "param"]，避免 shell 格式导致信号传递问题。

ARG vs ENV 4/6

维度ARGENV
作用范围仅构建阶段构建 + 运行时
运行时可用❌✅
docker run 覆盖通过 --build-arg通过 -e 或 --env-file
典型用途版本号、构建参数运行时配置、API 地址
安全性构建后从镜像移除保留在镜像中（不要存密码！）
# ARG：构建时变量
ARG VERSION=22
FROM node:${VERSION}-alpine

# ENV：运行时变量
ENV NODE_ENV=production
ENV APP_PORT=3000

# ARG 可赋值给 ENV（传递到运行时）
ARG BUILD_VERSION=1.0
ENV APP_VERSION=${BUILD_VERSION}

镜像瘦身对比 5/6

node:22
~1.1 GB
node:22-slim
~240 MB
node:22-alpine
~180 MB
多阶段构建
~45 MB
基础镜像大小优点缺点
node:22~1.1 GB完整工具链，兼容性最好体积大，攻击面大
node:22-slim~240 MB精简 Debian，兼容性好缺少编译工具
node:22-alpine~180 MB体积最小，安全musl 兼容性问题
多阶段构建~45 MB只含产物，最安全需额外 Dockerfile 配置

hadolint 在线检查 6/6

粘贴你的 Dockerfile，前端规则匹配检查（基于常见 hadolint 规则集）。