执行 docker compose up -d 时出现 network ... declared as external, but could not be found，说明Compose文件把该网络标记为外部资源，但当前连接的Docker Engine中没有同名网络。这不是镜像拉取失败，也不是容器内DNS故障。
Docker官方规范明确说明，external: true 表示网络生命周期由应用之外维护，Compose不会替你创建；网络不存在时，启动必须报错。
先看Compose最终解析出的网络名
变量、多个Compose文件和项目目录都可能改变最终配置。先让Compose渲染结果：
docker compose config
docker compose config --networks再列出当前Engine中的网络：
docker network ls
docker network inspect shared_backend报错中缺少的是平台上的真实网络名，不一定等于YAML里的逻辑键名。 配置使用 name: 后，Compose会按该值原样查找，不再自动加项目名前缀。
external true到底改变了什么
下面的配置要求复用已经存在的 shared_backend：
services:
app:
image: example/app
networks:
- backend
networks:
backend:
external: true
name: shared_backend对于外部网络，Compose只负责查询和连接，不负责创建或删除。官方规范还规定，除 name 外再设置 driver、ipam 等网络属性会使配置无效。
不要期待 docker compose down 管理外部网络，也不要把需要自动创建的项目私有网络标记成external。 是否使用external取决于该网络是否需要被多个项目长期复用。
需要共享网络时先显式创建
确认多个Compose项目确实要共享同一bridge网络后，可以在同一个Docker Engine上创建：
docker network create shared_backend
docker network inspect shared_backend
docker compose up -d创建前先核对网段，避免与宿主机、VPN或其他Docker网络重叠。普通单机Compose通常使用bridge网络；Swarm的overlay网络需要已初始化Swarm，并按部署方式决定是否使用 --attachable。
不要在不清楚驱动和网段的情况下照搬 docker network create 参数。 已存在同名但驱动不符合需求的网络，应先评估其连接容器，不能直接删除重建。
只属于当前项目时交给Compose管理
如果该网络不需要跨项目共享，删除 external: true 与固定 name:，让Compose创建项目作用域网络：
services:
app:
image: example/app
networks:
- backend
networks:
backend: {}重新运行后，网络名通常带有Compose项目名前缀。可用下面的命令确认容器实际连接关系：
docker compose up -d
docker compose ps
docker network ls --filter label=com.docker.compose.project共享网络与项目私有网络是两种不同的生命周期设计。 为了消除一条报错而固定网络名，会增加不同环境之间的冲突风险。
别忽略Docker context和权限范围
本机看得到网络，Compose仍提示不存在时，常见原因是命令连接到了另一台Engine、rootless实例或不同context：
docker context show
docker context ls
docker info --format '{{.Name}} {{.DockerRootDir}}'使用 sudo docker network ls 与普通用户执行 docker compose 也可能访问不同daemon配置。创建网络和启动Compose必须指向同一个Docker Engine。 不要在多个context中都创建同名网络来掩盖连接目标错误。
需要搭建跨项目容器网络测试环境时，可用 萤光云 准备隔离主机，或在 LightNode 按小时开机验证。上线前仍要按实际VPC和宿主网段重新规划地址。
修改后如何验收
先做配置校验，再启动并检查网络成员：
docker compose config --quiet
docker compose up -d
docker compose ps
docker network inspect shared_backend若改为项目管理网络，应把最后一条命令替换成实际生成的网络名。随后从容器内按服务名测试目标端口，而不是只做ping。
验收标准是Compose可重复启动、所有服务连接到预期网络，并且down操作不会误删需要共享的外部网络。 同时确认没有创建拼写相近的重复网络。
FAQ
为什么加了external后Compose不自动创建网络？
因为external的含义就是资源由Compose之外维护。需要自动创建时，应去掉external并让网络归当前项目管理。
YAML键叫backend，为什么它查找shared_backend？
backend是Compose内部引用名；设置 name: shared_backend 后，平台网络使用后者，并且不会自动添加项目名前缀。
能直接删除同名网络再创建吗？
应先运行 docker network inspect 确认已连接容器。删除正在使用的共享网络会中断其他项目，需在维护窗口内规划迁移。
温馨提示
处理外部网络错误前，先确定网络由谁创建、谁删除、哪些项目共享。 名称修正只是表面，生命周期和网段规划清楚后，Compose部署才不会在下一次迁移或重建时再次失败。
