编写 Docker 镜像时，总会遇到那个神秘的 entrypoint.sh 文件。它看起来只是一个普通的脚本，却承担着容器启动时的核心职责。很多人直接照搬网上的模板，却并不清楚它到底在做什么，更不知道如何根据业务需求定制它。其实 entrypoint.sh 的设计哲学很简单，就是让容器能够优雅地初始化环境并正确启动主进程，下面我们来彻底搞懂它。
为什么 docker entrypoint.sh 必须存在
entrypoint.sh 的核心价值在于解耦初始化逻辑与主应用进程。在容器化环境中，仅仅运行一个主程序往往不够，我们可能需要在启动前生成配置文件、等待依赖服务就绪或者检查环境变量。把这些操作塞进应用代码里会增加耦合docker entrypoint.sh，而写在 Dockerfile 里又不够灵活。entrypoint.sh 作为一道桥梁，在容器启动时先执行一系列准备工作，最后再通过 exec 拉起主进程，保证 PID 1 的正确性，从而让容器能够正常接收信号。
如何编写一个健壮的 entrypoint.sh
一个健壮的 entrypoint.sh 首先要保证安全性。脚本开头必须添加 #!/bin/bash 并设置 set -e 来确保任何命令失败时脚本立即退出，避免出现未知状态。同时要正确处理传入的参数，通常的做法是如果用户传入了自定义命令，则直接执行用户命令而不启动默认服务。最后一步必须使用 exec "$@" 来将控制权转交给主进程，确保信号能够穿透到子进程，这直接关系到容器能否被优雅停止。
如何调试 docker entrypoint.sh 不生效
遇到 entrypoint.sh 不生效的情况，先检查脚本是否具有可执行权限，很多人在构建镜像时忘了执行 chmod +x entrypoint.sh，导致容器运行时无权执行该脚本。其次要确认 Dockerfile 中是否正确使用了 ENTRYPOINT 指令linux操作系统好吗，比如 ENTRYPOINT ["/entrypoint.sh"] 的 JSON 数组格式与字符串格式的行为是不同的。还可以在容器启动时用 docker run --entrypoint sh 覆盖入口点，进入容器手动执行脚本查看具体错误日志。
如何传递环境变量给 entrypoint.sh
entrypoint.sh 内可以直接访问所有通过 -e 参数传入的环境变量linux游戏，也可以读取 Dockerfile 中 ENV 定义的值。但要注意，如果通过 supervisor 或 tini 启动进程，环境变量的传递方式会发生变化。在脚本中处理变量时建议给默认值，例如 ${DB_HOST:-localhost}，这样即使变量未定义也不会导致脚本中断。敏感信息如密码不建议硬编码在脚本里，而是通过 secrets 机制挂载为文件，在脚本中读取文件内容。
如何兼顾开发环境和生产环境的启动逻辑
很多团队希望在开发环境和生产环境使用同一份 entrypoint.sh，这时可以依靠环境变量来区分。比如开发环境可能需要启动调试工具或热重载服务，可以通过 if [ "$ENV" = "development" ] 条件判断来执行不同逻辑。也可以根据传入命令的不同来决定行为，例如执行 docker run image composer install 时，脚本应该直接执行 composer 而不是启动应用，这就需要脚本中判断 $1 参数，灵活决定流程。
如何优雅处理容器停止时的清理工作
容器被停止时，主进程会收到 SIGTERM 信号，这个信号能否传递给实际应用取决于 entrypoint.sh 的写法。如果直接使用 exec "$@" 启动主进程，信号会被正确传递。如果脚本中启动了后台进程而没有用 exec，那么主进程可能是 shell 而不是你的应用，信号会被 shell 拦截。需要清理的临时文件可以在脚本中注册 trap，捕获 EXIT 信号执行清理命令，确保每次退出都保持干净状态。
如何复用他人写好的 entrypoint 脚本
GitHub 上有大量优秀项目的 entrypoint.sh 可供参考，比如 MySQL、Redis、Nginx 官方镜像的脚本。但直接复制过来往往不适用，需要理解其设计思路。可以重点关注它们如何处理参数、如何替换配置文件中的占位符、如何判断首次启动与重启启动。很多通用模式如等待数据库就绪、生成密码文件等都可以抽取出来放入自己的脚本，但要确保修改后的逻辑符合自身业务场景。
你在编写 entrypoint.sh 时遇到过哪些奇怪的坑？欢迎在评论区分享你的经历docker entrypoint.sh，一起探讨如何写出更健壮的容器启动脚本，别忘了点赞收藏让更多小伙伴看到这些实战经验。
