Docker Compose 改了配置不生效：4 个真实报错复盘

写代码久了，我最怕的一句话是：「我明明改了配置，为什么没生效？」

这句话在自托管场景里出现得尤其频繁。它不一定是代码 bug，更多时候是部署工具的配置生效机制和你的直觉不一致。我在这台机器上管理着十几个 Compose 项目，踩过的坑可以归成一句话：容器的配置在创建那一刻就固化了，restart 只是让同一个容器里的进程再跑一遍，它永远不会重新读你的 YAML。

这篇文章不讲怎么搭建服务，只讲一件事：配置为什么没生效，以及怎么在 5 分钟内定位到具体是哪一层把它吃掉了。全文的命令都可以直接复制。

声明：本文包含 Amazon 联盟链接。你通过链接下单时价格不变，我会获得少量佣金。文中提到的硬件均为自费购买，价格为截至发稿的常见区间，请以商品页实际报价为准。

先建立正确的心智模型：restart 和 up -d 根本不是一回事

很多人踩的第一个坑，是把 docker compose restart 当成「应用新配置」。它不是。

容器的环境变量、端口映射、挂载路径、启动命令、运行用户、镜像 ID，这些全部在**容器被 create 的那一刻**写进容器自己的记录里。restart 做的是给主进程发停止信号，然后在**同一个容器**里再启动一次。既然容器没换，这些字段自然一个都没变。

所以下面这些改动，restart 之后一定是原样：

• 改了 `docker-compose.yml` 里的 `ports:`、`volumes:`、`environment:`、`command:`
• 改了 `.env` 里的值（Compose 在**渲染服务定义**时读 `.env`，不是在启动进程时读）
• 改了 `env_file:` 指向的文件（同样在渲染阶段就被解析进定义了）
• 换了镜像（容器还在跑它被创建时那个 image）

真正会生效的命令是 docker compose up -d。它的工作方式是：读取 Compose 文件、解析所有变量、算出渲染后服务定义的哈希值，把这个哈希作为 label 打在容器上；下次执行 up -d 时再算一次哈希，和容器上那个 label 比。**哈希不同才重建，哈希相同就什么都不做。**

这一条同时解释了另一个常见困惑：「我改了配置，up -d 却什么都没干」。不是它坏了，是真的没变化——要么你改的地方根本没进渲染结果（比如改了一个不存在的 key），要么改动被别的地方覆盖了。

还有一个版本坑：老的 docker-compose（带连字符，Python 版 V1）已经不在当前软件包里了。2026 年 7 月之后在全新的 Ubuntu 上敲 docker-compose 得到 command not found 是**预期行为**，不是环境坏了。现在统一用带空格的 docker compose，它是随 Docker Engine 安装的 Go 插件，也就是 Compose V2。用 docker compose version 确认版本。

命令阶梯：按你改了什么来选，不要一律用最重的

从最便宜的 rung 开始往上爬，能省下大量无谓的重建和停机。

这张表里最反直觉的两行是第一行和第二行。restart 不是 reload，exec ... reload 才是 reload。如果你的 nginx 配置目录是从宿主机 bind mount 进去的，改完宿主机上的文件，容器本身根本不需要变，直接在容器内重载即可——这比重建容器温和得多，不会丢掉正在服务的连接。

反过来，「更新镜像」需要**两条命令**。pull 负责把新镜像拉下来，up -d 才负责发现 image ID 变了并重建。只跑 up -d 不 pull，你会安安静静地继续跑上个月的 latest，而且没有任何报错。

还有一个自动化相关的细节值得记住：up -d 在容器创建后就返回了，所以「跑完 up -d 紧接着 curl 探活」的部署脚本**经常在第一次就失败**。要让它等，就用 up -d --wait：它会阻塞到所有声明了 healthcheck 的服务都报告 healthy，如果有服务一直不健康则以非零码退出。这个 flag 有多好用，取决于你写的 healthcheck 是否真的可信——所以在自动化里用之前，先把 healthcheck 写扎实。

报错一：改了 .env，服务还在用旧值

这是我见过频率最高的一个。日志里没有任何异常，服务只是安静地忽略了你的改动。

真实报错/现象通常是应用侧的配置缺失或回退，比如数据库连不上、端口还是旧的那一个，或者日志里打印的 config 值和你刚写的不一样。

原因在于 .env 是在 Compose **渲染服务定义**时被读进来的，读完就固化进定义了。restart 根本不重新渲染。

诊断顺序：

# 1. 看渲染后的最终定义，确认你的值到底有没有进来
docker compose config

# 2. 看容器上记录的哈希标签
docker inspect --format '{{ index .Config.Labels "com.docker.compose.config-hash" }}' <容器名>

# 3. 直接看容器里真正生效的环境变量
docker compose exec web env | grep MY_VAR

如果第 1 步 docker compose config 打印出来的就是你改过的新值，而第 3 步还是旧值，那就是没重建。跑 docker compose up -d <服务名>。如果第 1 步打印的还是旧值，问题在渲染层——常见原因是 env_file: 指向的文件不存在，或者你在错误的目录执行（Compose 从当前目录取项目名和文件位置，在上一级目录跑会直接报 no configuration file provided: not found）。

报错二：systemd drop-in 写完了，服务行为一点没变

场景是这样的：你不想直接改 /lib/systemd/system/nginx.service（包管理器升级会覆盖你的改动），于是写了个 drop-in。结果 systemctl restart 之后配置完全没生效。

最常见的报错文本：

Failed to read drop-in file /etc/systemd/system/nginx.service.d/override.conf:
Syntax error

或者更隐蔽的一种——不报错，但你写的东西根本没被读：

# 文件名叫 override.txt —— systemd 直接无视，因为它要求 .conf

systemd 对 drop-in 的规矩相当死板：

• 目录名必须是 `<完整单元名>.d`，也就是 `nginx.service.d`，不能是 `nginx.d`
• 文件名**必须以 `.conf` 结尾**
• 放在 `/etc/systemd/system/` 下，优先级高于 `/run/` 和 `/usr/lib/`
• 多个 drop-in 按文件名字典序叠加

写完之后**必须** systemctl daemon-reload。systemd 把单元文件读进内存后就不会再看磁盘，你改了文件但没 reload，等于什么都没做：

sudo systemctl edit nginx.service      # 交互式写 drop-in，最不容易写错
sudo systemctl daemon-reload
sudo systemctl restart nginx

改完想确认 systemd 到底用了什么，用 systemctl cat nginx.service 看合并后的结果——它显示的是**实际生效**的单元内容，比直接读磁盘上的文件可靠。

报错三：Service has more than one ExecStart= setting

这个报错在写 drop-in 覆盖 ExecStart 时出现：

nginx.service: Service has more than one ExecStart= setting in drop-in.
Refusing.

原因是 ExecStart= 是列表类型的指令，drop-in 里再写一条会**追加**而不是覆盖，于是就有了两条。systemd 的规则是：**用一条空赋值先清空，再写新值**。

[Service]
ExecStart=
ExecStart=/usr/local/bin/nginx -c /etc/nginx/my.conf

同理，OnCalendar=（timer 里加第二个触发时间导致定时器跑两次）、Environment= 之类的列表型指令都是这个规则。单个值的指令直接写就是覆盖，不需要清空。

另一个方向相反的坑：依赖是**加不上去也删不掉**的。Requires=、After= 这些没法通过 drop-in 移除，想彻底换掉一个单元，得用 systemctl edit --full 写完整单元，或者 mask 掉重新定义。

想审计整台机器上有哪些单元被 drop-in 覆盖过、哪些被完整复制冻结了，跑：

systemctl daemon-reload
systemd-delta --type=overridden

完整复制单元文件是最坏的情况——它把上游的单元冻住了，包升级的新内容永远到不了你这里。

报错四：unit 改对了，但服务起不来

drop-in 语法没问题，daemon-reload 也跑了，systemctl start 却失败。这时报错通常长这样：

myapp.service: Failed at step EXEC spawning /opt/myapp/bin/myapp: No such file or directory

或者更常见的反复重启：

myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'exit-code'.
systemd: Failed to start MyApp daemon.

第一种是 ExecStart 指向的路径不存在或没有执行权限，直接 ls -l 确认；第二种是应用自己起来了又立刻退出，而 Restart=on-failure 把它立刻拉回来，于是撞上速率限制。这时候**别盯着 restart 策略看日志，要看应用为什么退出**：

sudo systemctl status myapp.service
sudo journalctl -u myapp.service -n 50 -o cat   # 过滤 systemd 封装信息，看应用自己的第一行报错

-o cat 这一步很关键。systemd 只告诉你「进程退出了」，真正的原因在服务自己的 stdout/stderr 里，不去掉封装根本看不到。

改配置前先验证语法，能省掉大量盲目重启：

sudo systemd-analyze verify /etc/systemd/system/myapp.service

它会解析单元、报告语法错误和未知指令，并检查 ExecStart= 引用的可执行文件是否存在。

版本相关的坑：升级 Compose 之后容器被重建了

2026 年 Compose 的 reconciliation 逻辑改动比较密集，如果你最近升级过，值得知道这几件事：

• **v5.2.0（2026-06-23）** 引入了观察状态与期望状态之间的新 reconciliation 算法，并标记为 minor 破坏性变更
• **v5.4.0（2026-08-03）** 把卷和网络的生命周期纳入 reconcile plan，卷重建和子网变更在 plan 里可见；修复了多平台构建的 manifest digest 取值
• **v5.5.0（2026-08-17）** overhauled 镜像 digest 的 reconciliation。**注意：升级后第一次跑 `compose up` 时，现有容器可能会被重建一次**，因为 digest 判断逻辑换了一套模型。这是一次性的，digest 落位之后就不会再有意外重建。

也就是说，升级 Compose 之后，如果你的脚本会 diff 容器 ID 并据此判断「有没有变更」，第一次运行的结果要单独确认，别直接当成异常。

五分钟排查清单

配置改了没生效，按这个顺序走一遍：

# 1. 渲染层：最终定义里有我的改动吗？
docker compose config | grep -i MY_VAR

# 2. 定义层：哈希变了吗？
docker inspect --format '{{ index .Config.Labels "com.docker.compose.config-hash" }}' <容器名>

# 3. 容器层：环境变量真的进来了吗？
docker compose exec <服务> env | grep MY_VAR

# 4. 挂载层：这是 bind mount 还是 named volume？
docker inspect <容器名> --format '{{json .Mounts}}'

# 5. 镜像层：我以为在跑新镜像，实际跑的是哪个 ID？
docker inspect <容器名> --format '{{.Image}}'
docker image inspect <镜像>: --format '{{.Id}}'

第 4 步经常被忽略。宿主机上改了文件，容器里看不到——如果那个挂载是 named volume 而不是 bind mount，宿主机目录和容器目录是两套完全独立的数据。这是另一个版本的「改了不生效」。

收尾：把生效机制变成默认习惯

我最后沉淀下来的规则只有三条：

1. **改了 Compose 文件，永远先 docker compose config 看渲染结果**，别改完就 up。这一条能挡掉绝大多数低级错误。

2. **restart 只用来拉崩溃的进程**，任何配置变更都走 up -d。构建产物变了才加 --build，镜像变了先 pull。

3. **永远不直接编辑 /lib/systemd/system/ 或 /usr/lib/systemd/system/ 下的文件**，用 drop-in，改完 daemon-reload，然后 systemctl cat 验证。

顺带一句：这台机器上跑着的一堆小服务，本质上都是「一台小主机 + 一堆容器」。如果你也在搭自己的实验环境，下面这三样是我实际在用的——一台树莓派 5 当常驻节点、一根 Cat6 网线做机柜连线、一张 microSD 存配置和日志。都是自费，价格以商品页为准。

👉 在 Amazon 上查看 Raspberry Pi 5（8GB）

👉 在 Amazon 上查看 Amazon Basics Cat6 网线

👉 在 Amazon 上查看 Amazon Basics microSD 卡 128GB

相关阅读

把自托管服务真正跑起来之后，下一步往往是怎么知道它活着、跑得怎么样。可观测性那套东西值得先搭起来——我在用 Langfuse 给自托管工作流加全链路追踪里记录过完整做法，Docker 和自托管的坑跟本文高度重叠。

如果你这堆服务是跟着 CI/CD 一起改的，那配置什么时候生效就不只是运维问题了，而是发布流程问题。GitHub Actions 供应链踩坑实录里记的是另一类「改了不生效」——action 的 tag 被改了，你以为在跑旧版本，其实跑的是别人。

👉 立即参与 MiniMax Token Plan：AI 编程加速，企业用户专享优惠

👉 立即参与小米 MiMo 开放平台：国内领先的 AI 大模型开放平台，高性价比推理服务

👉 立即参与阿里云 AI：汇集爆款 AI 产品，热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点，专注于效率工具与 SaaS 真实评测