用 Codex 写 Dockerfile

用 Codex 写 Dockerfile，不是让它套一个通用模板，而是让它读取真实项目、识别运行脚本、判断构建产物、生成 .dockerignore，再用 docker build 和 docker run 把结果验证出来。适合把 Node、Python、文档站、内部工具和 AI 服务整理成可交付的容器入口。

容器能跑，再接入 AI 能力

如果容器里的服务需要调用 OpenAI-compatible API，可以在运行时注入 OfApp.cn 的 Base URL 和 API Key。示例只使用假 Key，真实模型、额度、价格和能力请以 OfApp.cn 控制台或官方文档为准。

打开 OfApp.cn

项目	说明
阅读时间	约 5 分钟
更新时间	2026-07-03
适合读者	开发者、独立站维护者、需要部署项目的产品或运营、正在学习 Codex 的用户
你会获得	Dockerfile 生成思路、可复制 Goal Prompt、Node 示例、.dockerignore 清单、排错路径和验收标准

使用场景

场景	重点	验证
Node Web 应用	锁文件、构建目录、启动脚本、端口	镜像能构建，容器能访问
Python API	依赖文件、入口模块、ASGI/WSGI 命令	健康检查返回正常
文档站	静态构建产物、预览服务或 Nginx	页面可访问，资源路径正确
AI 服务	环境变量、超时、日志脱敏、重试边界	不把 API Key 写进镜像
多包仓库	工作目录、子包依赖、构建缓存	只复制必要包和产物

工作流图

推荐目录结构

project/
  Dockerfile
  .dockerignore
  package.json
  src/
  .env.example

.dockerignore 和 Dockerfile 同样重要。Docker 官方文档也强调，构建上下文会影响性能、镜像体积和泄露风险。不要把 node_modules、.git、本地密钥、数据库文件、测试缓存和构建产物都复制进镜像。

可复制 Goal Prompt

Goal: 为当前项目生成可构建、可运行、可部署前复核的 Dockerfile 和 .dockerignore。

请先读取项目结构和运行脚本，确认：
- 语言和版本
- 安装命令
- 构建命令
- 启动命令
- 暴露端口
- 必需环境变量

完成后给出：
1. Dockerfile
2. .dockerignore
3. docker build/run 验证命令
4. 镜像体积、密钥泄露、端口和健康检查的复核清单
5. 你没有确认的信息，以及需要我人工决定的部署参数

如果项目已经有 AGENTS.md，把 Docker 相关约束写进去会更稳，例如基础镜像策略、禁止复制 .env、必须运行的构建命令、部署平台端口要求和镜像命名规则。Codex 官方手册也建议把长期有效的仓库规则放进 AGENTS.md，让每次任务都能继承同一套项目约定。

执行步骤

1. 让 Codex 查看 package.json、锁文件、入口文件、README、环境变量样例和部署说明。
2. 要求它列出安装、构建、启动、测试和端口来源，不确定的地方必须标注。
3. 选择单阶段或多阶段构建。带前端构建、编译步骤或大量开发依赖的项目，通常更适合多阶段构建。
4. 生成 Dockerfile 与 .dockerignore，并解释每一段解决什么问题。
5. 执行 docker build，保留失败日志，让 Codex 基于日志做小范围修复。
6. 用假环境变量或本机 Secret 运行容器，检查端口、日志、健康检查和关键页面。
7. 复核 git diff，确认没有真实 Key、私有文件或无关格式化改动。

Codex 应该先读什么

文件或命令	目的	需要 Codex 输出什么
package.json / pyproject.toml / requirements.txt	确认语言、依赖和脚本	安装、构建、启动命令来源
锁文件	保证依赖可复现	用 npm ci、pnpm install --frozen-lockfile 或对应命令
README / 部署说明	找端口、运行方式和外部服务	不确定项清单
.env.example	识别环境变量名	只写变量名和假值
入口文件	确认监听地址和端口	是否监听 0.0.0.0
现有 CI	复用构建命令	Docker 验证应和 CI 接近

Dockerfile 评审矩阵

维度	好的信号	需要重写的信号
基础镜像	与项目运行时版本一致，来源清晰	版本随手猜，或使用过大的通用镜像
依赖安装	先复制锁文件，利用缓存	直接 COPY . . 后再安装依赖
构建策略	构建依赖不进入运行镜像	编译器、测试缓存、源码全塞进运行镜像
.dockerignore	排除 .git、.env、缓存、构建产物	构建上下文巨大，或把密钥复制进去
用户权限	能用非 root 用户运行时优先考虑	生产服务默认 root 且无说明
环境变量	运行时注入，文档给假值	ENV OPENAI_API_KEY=... 写进镜像层
健康检查	有端口、路径或进程验证	只看容器是否启动
验证命令	build/run/logs 都可复现	只给文件，不给验证路径

示例：Node Web 应用 Dockerfile

下面示例只演示结构，版本和构建目录要按你的项目调整。让 Codex 生成时，应要求它说明为什么选择这些命令。

# syntax=docker/dockerfile:1
ARG NODE_VERSION=22-alpine

FROM node:${NODE_VERSION} AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM deps AS build
COPY . .
RUN npm run build

FROM node:${NODE_VERSION} AS runner
WORKDIR /app
ENV NODE_ENV=production

COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist

USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

这个结构把安装依赖、构建和运行拆开，便于缓存，也能避免把构建工具全部带进运行阶段。静态站点可以把运行阶段换成 Nginx 或平台指定的静态服务；服务端应用则要确认启动文件、监听端口和部署平台要求。

.dockerignore 基础清单

.git
.github
.env
.env.*
node_modules
dist
build
coverage
.cache
.astro
.next
.turbo
npm-debug.log
Dockerfile*
docker-compose*.yml
README.md

不要机械复制这份清单。比如文档站可能需要 README.md 进入构建上下文，某些平台也可能需要 compose 文件。更稳的做法是让 Codex 根据项目解释“排除什么、保留什么、为什么”。

容器内调用 API 的写法

Dockerfile 不应该保存真实 API Key。容器需要调用 OpenAI-compatible API 时，用运行时环境变量注入：

docker run --rm -p 3000:3000 \
  -e OPENAI_BASE_URL="https://api.ofapp.cn/v1" \
  -e OPENAI_API_KEY="sk-xxxx" \
  my-app:local

sk-xxxx 只是占位。真实 Key 放在本机环境变量、部署平台 Secret 或密钥管理服务里。涉及 OfApp.cn 的模型、能力、额度和价格，请以 OfApp.cn 控制台或官方文档为准。

注意事项

风险	处理方式
镜像过大	使用合理基础镜像、多阶段构建和 .dockerignore。
复制密钥	不复制 .env，不把 Key 写进 ENV，运行时注入变量。
构建命令错误	命令必须来自项目脚本、README 或 CI，不要凭空猜。
本地能跑容器不行	检查端口、host、文件路径、权限和监听地址。
构建慢	先复制锁文件再安装依赖，减少无关文件进入上下文。
运行时缺文件	对照构建产物目录，不要只凭框架名称推断。

验证命令

目标	命令
构建镜像	docker build -t my-app:local .
查看镜像	docker images my-app
运行容器	docker run --rm -p 3000:3000 my-app:local
查看日志	docker logs <container-id>
进入容器排查	docker exec -it <container-id> sh
检查页面	curl http://localhost:3000/

把这些命令也写进 Codex 的完成条件。只有文件生成，没有构建和运行证据，不能算交付完成。

常见错误排查

错误	表现	修复
COPY 了本地 .env	密钥进入镜像或构建日志	加入 .dockerignore，重建镜像并检查历史层
启动命令不对	容器立即退出	对照项目脚本和入口文件
端口没映射	浏览器访问失败	确认应用监听端口、EXPOSE 和 docker run -p
监听 localhost	容器外访问不到	让服务监听 0.0.0.0
构建产物路径错	运行时报找不到文件	检查 dist、build、.next 或框架输出目录
依赖不一致	本地能跑，容器内安装失败	使用锁文件和可复现安装命令
镜像体积异常	推送慢、扫描风险多	使用多阶段构建，排除缓存和开发依赖

资料来源

• Docker multi-stage builds：多阶段构建可以分离构建环境和运行环境，减少镜像体积与攻击面。
• Docker .dockerignore reference：.dockerignore 用于控制进入构建上下文的文件。
• OpenAI Codex 官方手册：Codex 任务更适合写清目标、上下文、约束、验证和完成条件。
• OfApp.cn API 文档：本站示例使用 OfApp.cn 的 OpenAI-compatible API 入口时，以官方文档和控制台为准。

常见问题

Codex 可以直接决定基础镜像吗？

可以提出建议，但不能替代项目约束。基础镜像应根据项目声明的运行时版本、部署平台、系统依赖、安全扫描和团队规范决定。Codex 应把选择理由写出来，缺信息时请你确认。

Dockerfile 需要多阶段构建吗？

有构建步骤的 Web 应用、编译型项目和带大量开发依赖的服务通常适合多阶段构建。小型脚本或简单 API 可以先从单阶段开始，但要保留后续压缩镜像和降低攻击面的空间。

API Key 应该写在 Dockerfile 里吗？

不应该。Dockerfile 只声明程序如何构建和运行，密钥通过运行时环境变量、部署平台 Secret 或密钥管理服务注入。文档和示例只写 sk-xxxx 这类假值。

.dockerignore 会不会影响构建？

会。它会决定哪些文件进入构建上下文。排除过多可能导致构建缺文件，排除过少会让构建变慢并增加泄露风险。让 Codex 每次改 .dockerignore 时说明原因。

需要把健康检查写进 Dockerfile 吗？

看部署平台。自托管服务可以用 HEALTHCHECK 或平台探针；云平台可能有自己的健康检查配置。关键是要有可复现的验证路径，而不是只看容器进程是否存在。

Codex 生成的 Dockerfile 可以直接上线吗？

不建议跳过人工复核。至少要检查基础镜像、依赖安装、端口、用户权限、密钥处理、镜像体积、漏洞扫描、部署平台要求和回滚方式。

相关文章

• Codex 教程：把任务写成可验证工作流。
• Codex Goal 提示词模板：写清目标、范围、验证和完成审计。
• Codex 本地项目使用指南：让 Codex 读项目、遵守 AGENTS.md 和运行验证命令。
• 用 Codex 配置 GitHub 工作流：在 CI 中构建镜像。
• 用 Codex 排查报错：处理容器启动失败。
• OpenAI-compatible API 快速开始：验证容器内 API 配置。
• 401 Unauthorized：排查密钥错误。

带走什么

用 Codex 写 Dockerfile 时，质量来自真实项目上下文和可验证结果。让它先读脚本和入口，再生成 Dockerfile、.dockerignore、构建命令、运行命令和排错清单。涉及 API Key 时只使用运行时注入；涉及 OfApp.cn 的可用模型、额度、价格和具体能力时，请以 OfApp.cn 控制台或官方文档为准。