Docker 开发环境到底要交付什么：镜像、源码与运行脚本
摘要：从团队交付角度区分 Docker 镜像、bind mount 源码、entrypoint、Compose 和 dev.sh，明确哪些需要随镜像一起交给使用者。
@[toc]
开发镜像自己能运行以后，下一个问题往往不是“怎么构建”，而是：
我要把这套环境给另一个开发者，他到底需要拿到哪些文件？
最容易产生误解的是 entrypoint.sh、compose.yaml 和 dev.sh。
它们看起来都和“启动容器”有关，但所处层次完全不同。
1. 先把开发环境分成三层
可以先用一张图建立边界：
1 | flowchart TB |
这三层分别回答不同问题：
1 | 镜像：容器里面有什么？ |
如果把它们混在一起，交付包往往会过大或者缺东西。
2. entrypoint.sh 通常已经进入镜像
Dockerfile 常见写法：
1 | COPY docker/entrypoint.sh /usr/local/bin/dev-entrypoint |
构建过程是：
1 | 宿主机 docker/entrypoint.sh |
镜像完成以后，真正运行的是镜像内部这份文件。
因此：
1 | docker save cross-dev:20.04 |
导出的镜像已经包含：
1 | /usr/local/bin/dev-entrypoint |
接收方 docker load 后直接：
1 | docker run --rm -it cross-dev:20.04 |
仍然会触发 entrypoint。
所以对于“只使用现成镜像”的人，通常不需要再额外提供原始 docker/entrypoint.sh。
原始脚本更属于“如何重新构建镜像”的源码。
3. compose.yaml 不在镜像里
compose.yaml 描述的是运行时配置，例如：
1 | services: |
它决定：
1 | 使用哪张镜像 |
这些信息并不是镜像文件系统的一部分。
尤其：
1 | volumes: |
这里的 ${WORKSPACE} 来自接收方宿主机。镜像不可能提前知道别人源码放在：
1 | /home/alice/project |
因此 compose.yaml 属于“如何使用镜像”，应该单独交付。
4. dev.sh 是更上层的开发入口
一个 dev.sh 常常会做：
1 | 解析项目路径 |
开发者最终只需要：
1 | ./scripts/dev.sh ~/work/demo-app |
而不是每次写：
1 | docker run --rm -it \ |
所以 dev.sh 不是 Docker 运行所必需的文件，却是团队使用体验的重要部分。
可以理解成：
1 | dev.sh |
5. bind mount 源码也不属于镜像
如果使用：
1 | -v ~/work/demo-app:/workspace |
那么源码位于宿主机。
容器中修改：
1 | /workspace/foo.cpp |
实际修改的就是宿主机：
1 | ~/work/demo-app/foo.cpp |
因此：
1 | docker save |
不会保存 bind mount 里的源码。
这反而是开发容器推荐的边界：
1 | 镜像保存稳定环境 |
镜像 20 多 GiB 没关系，日常代码变更不需要重新构建镜像。
6. 只给镜像能不能用
可以。
如果对方熟悉 Docker，只提供：
1 | cross-dev.tar.zst |
他可以：
1 | docker load -i cross-dev.tar.zst |
然后自己运行：
1 | docker run --rm -it \ |
技术上完全成立。
问题是使用者必须自己知道：
1 | 挂载路径 |
团队里每个人手写一次，很容易逐渐出现不同运行方式。
7. 更适合普通开发者的“使用包”
如果目标是“拿到以后尽量一条命令使用”，可以提供：
1 | developer-environment/ |
使用流程：
1 | 导入镜像 |
这时普通开发者甚至不需要知道镜像是怎么构建的。
8. “镜像构建源码包”应该另外维护
镜像维护者还需要：
1 | Dockerfile |
这些文件回答的是：
如果以后 SDK 更新、依赖变化或者镜像丢失，如何重新制造同一类镜像？
所以可以把交付分为：
1 | 使用包 |
实际项目中，两者也可以都保存在 Git 仓库，只是在离线交付时不一定要把所有构建资产都发给使用者。
9. dev.sh 和 Compose 为什么最好成对维护
如果 dev.sh 最终调用 Compose：
1 | WORKSPACE="$WORKSPACE" docker compose run --rm dev |
那么它们实际上共同定义了启动契约。
dev.sh 负责动态部分：
1 | 用户输入的项目路径 |
compose.yaml 负责声明式部分：
1 | image |
因此给别人时只给 dev.sh、不带 compose.yaml，通常没有意义。
反过来，只给 Compose 也能用，但失去了统一入口和参数检查。
10. 为什么不建议把源码 COPY 进开发镜像
有人为了“一个 tar 全带走”，会考虑：
1 | COPY demo-app /workspace |
这样 docker save 确实会把源码一起带走。
但开发镜像通常不推荐这么做。
因为源码每天变化，SDK 和工具链却很少变化。
如果把二者绑在一起：
1 | 改一行源码 |
这完全破坏了开发镜像的价值。
更合理的是：
1 | 稳定环境 -> Image |
11. 路径和 UID/GID 是交付时真正要写清的内容
团队交付文档不能只写：
1 | ./scripts/dev.sh |
至少应该说明：
1 | Docker Engine 最低要求 |
特别是 bind mount 可写目录。
如果容器用户 UID 与宿主机用户不一致，可能出现：
1 | 容器生成 root:root 文件 |
因此 dev.sh 中的 UID/GID 处理不是装饰，而是开发环境可用性的一部分。
12. 一个比较清晰的最终边界
可以把整套交付关系记成四句话：
1 | Dockerfile / entrypoint.sh |
因此，“dev.sh + compose.yaml + entrypoint.sh 是否必须跟镜像一起给别人”这个问题的答案是：
1 | entrypoint.sh：通常已经打进镜像，不需要作为运行附件重复提供 |
如果只是给 Docker 熟练用户临时验证，镜像本身就能运行；如果要形成可长期复用的团队开发环境，最好把镜像和宿主机启动工具一起交付。
参考资料
- Docker Docs：What is an image? — https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/
- Docker Docs：Sharing local files with containers — https://docs.docker.com/get-started/docker-concepts/running-containers/sharing-local-files/
本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 wdfk-prog的个人博客！
微信- 支付寶
相关推荐
2026-09-03
01-Docker开发环境容器化：从基本概念到Ubuntu20
Docker 开发环境容器化：从基本概念到 Ubuntu 20.04 安装排查 摘要：从 Image、Container、Dockerfile 和挂载建立 Docker 心智模型，并结合 Ubuntu 20.04 的安装冲突说明为什么要把旧开发环境容器化。 @[toc]学习 Docker 最容易走偏的方式，是先背几十条命令，再去想这些命令解决什么问题。对于开发环境容器化，更合理的顺序正好相反：先明确工程为什么需要 Docker，再理解 Image、Container、Dockerfile、挂载和权限这些概念，最后才把命令放进实际场景。 本文从一个典型的嵌入式交叉编译环境出发：旧工程长期依赖 Ubuntu 20.04、厂商 Yocto SDK、固定 CMake、代码生成工具和若干宿主机软件。旧机器能稳定构建，但一旦换电脑、升级系统或让其他开发者接手，就很难准确复刻环境。 Docker 在这里的目标不是“把 Linux 再装一遍”，而是： 把构建环境固定成可重复生成的镜像，把日常修改的源码继续留在宿主机。 1. 为什么开发环境值得容器化传统开发机往往随着项目迭代逐渐变成这样...
2026-09-03
02-大型SDK开发镜像工程化：BuildKit、Buildx与项目脚本
大型 SDK 开发镜像工程化：BuildKit、Buildx 与项目脚本 摘要：以约 25 GiB 的交叉编译 SDK 为例，解释 BuildKit、Buildx、named context、镜像层，以及 Dockerfile、Compose 和配套脚本怎样组成完整开发环境。 @[toc] 普通 Docker 教程经常从一个几十 MB 的源码目录开始：写 Dockerfile、COPY . .、执行 docker build，几秒钟就能看到结果。但真实嵌入式开发环境可能完全不是这个规模。 假设已有一套厂商 Yocto SDK，展开后约 25 GiB，还需要固定版本的 CMake、host 侧代码生成工具以及一套 UID/GID 兼容逻辑。此时问题已经从“会不会写 Dockerfile”变成了： 25 GiB SDK 怎样进入 Image； 怎样避免为了构建镜像再制造一个巨大的 SDK 压缩包； BuildKit 和 Buildx 分别负责什么； 为什么使用额外 build context； 为什么源码不和 SDK 一起做进 Image； 为什么需要 entry...
2026-09-03
03-交叉编译开发容器故障排查：从CMakeCache到目标库链接
交叉编译开发容器故障排查：从 CMakeCache 到目标库链接 摘要：按真实首次失败点复盘旧 CMakeCache、host/target Thrift、SDK 权限、编译参数冲突和目标库链接，说明怎样沿证据链逐层收敛问题。 @[toc] Docker 能启动、交叉编译器能执行，只能证明环境最外层入口正常。历史 C/C++ 工程仍可能依次暴露旧 CMake 缓存、宿主工具、目标库、权限和编译参数策略。 这次排查最重要的原则是：围绕当前第一次失败收集证据，证明后再继续向后。 最终故障链可以概括为： 1234567flowchart TD Cache["旧 CMakeCache\n编译器路径属于旧 Host"] -->|干净 build tree| Compiler["交叉 GCC 正确识别"] Compiler --> Thrift["host Thrift 查找失败"] Thrift -->|确认 host generator| Header["...
2026-09-03
04-Docker常用语法与命令：CLI、Dockerfile与Compose速查
# Docker 常用语法与命令：CLI、Dockerfile 与 Compose 速查 摘要：用开发环境场景整理 Docker CLI、Dockerfile、Buildx、Bind Mount、Compose、镜像迁移与磁盘清理的常用语法，重点解释参数改变了什么。 @[toc] 这一篇把前面频繁出现的 Docker 语法集中成开发机速查表，不穷举全部参数，只保留最常用对象和命令结构。 1. Docker CLI 先按“对象 + 动作”理解现代 Docker CLI 很多命令可以读成： 1docker <object> <command> [options] 例如： 123456docker image lsdocker image inspect arm64-dev:20.04docker container lsdocker container rm demodocker volume lsdocker network ls 同时 Docker 仍保留大量短写： 1234docker imagesdocker psdocker rmdoc...
2026-09-04
05-Docker开发镜像跨主机迁移：从Ubuntu20
Docker 开发镜像跨主机迁移：从 Ubuntu 20.04 到 24.04 摘要：说明如何把已验证的 Ubuntu 20.04 开发镜像迁移到 Ubuntu 24.04，并逐层验证 Docker、镜像、源码挂载和真实构建。 @[toc]旧开发机长期使用 Ubuntu 20.04，交叉编译 SDK、CMake 和各种依赖已经调通；新机器升级到 Ubuntu 24.04 后，最稳妥的做法往往不是重装整套依赖，而是继续运行已经验证过的开发镜像。 1. 宿主机升级，不等于容器也升级假设我们已经有一张镜像： 1cross-dev:20.04 它内部包含： 123456Ubuntu 20.04 用户空间Yocto SDK交叉编译器CMake / Make / Python代码生成工具entrypoint 把它迁移到 Ubuntu 24.04 后，结构是： 123456flowchart TB Host["Ubuntu 24.04 宿主机"] --> Engine["Docker Engine"] Engine --&g...
2026-09-04
07-大型Docker镜像导出导入工程化：可靠性、磁盘与压缩
大型 Docker 镜像导出导入工程化：可靠性、磁盘与压缩 摘要：分析二十多 GiB Docker 镜像在 save/load、临时 TAR、流式压缩、SHA256 和 zstd 之间的工程取舍，并给出更省磁盘的脚本结构。 @[toc]普通镜像只有几百 MB 时，docker save 和 docker load 很少让人关心磁盘峰值。 但开发镜像如果包含完整 Yocto SDK，规模达到二十多 GiB，导出本身就会变成一个值得设计的流程。 真正的问题不再只是： 1怎么导出？ 而是： 12345失败时会不会留下假成功文件？Ctrl+C 会不会留下几十 GiB 垃圾？临时 TAR 会占多少磁盘？压缩包是否需要先解压才能 docker load？如何校验传输完整性？ 1. save/load 的基本数据流导出： 1docker save -o cross-dev.tar cross-dev:20.04 导入： 1docker load -i cross-dev.tar 可以理解成： 12345Docker image ↓ docker save...
评论
