跨平台部署需结构化适配路径、变量、权限和启动时序：统一用相对路径+正斜杠挂载，优先命名卷，环境变量用${var}格式，依赖服务配置healthcheck并设condition: service_healthy，显式声明ro权限或使用命名卷规避权限问题。
跨平台部署不是“写完就跑”，而是要主动适配 Windows、macOS 和 Linux 三类环境的底层差异。核心在于路径、变量、权限和启动时序这四个关键点，不靠猜测，靠结构化约束。
统一用相对路径 + 正斜杠
绑定挂载（volumes）是最容易出问题的地方。Windows 习惯用 C:\project\src，Linux 用 /home/user/project/src，但 Docker Compose 在所有平台上都支持以 . 开头的相对路径和正斜杠分隔符。
- ✅ 推荐写法：
- ./src:/app/src:ro、- ./config:/etc/app - ❌ 避免写法：
- C:\project\src:/app/src（Windows 专属）、- /home/user/project/config:/etc/app（Linux 专属） - 命名卷（如
db_data:）天然跨平台，优先用于数据库等有状态服务
环境变量引用保持 POSIX 格式
Docker Compose 解析 ${VAR} 是标准行为，而 Windows 命令行原生用 %VAR%。如果在 shell 脚本或 CI 中动态生成 compose 文件，务必统一用 ${VAR}；.env 文件本身也只认这种格式。
-
.env文件中写：DB_HOST=db、LOG_LEVEL=info - compose 文件中引用：
environment: - DB_HOST=${DB_HOST} - 避免在
.env中写PATH=C:\tools这类系统路径——它对容器无意义，还可能干扰解析
用健康检查替代简单 depends_on
depends_on 默认只等容器启动，不等服务就绪。Linux 启动快，Windows/macOS 可能慢几百毫秒，导致应用连接失败。
- 为依赖服务加
healthcheck，例如 PostgreSQL： healthcheck:<br> test: ["CMD-SHELL", "pg_isready -U postgres"]<br> interval: 10s<br> timeout: 5s<br> retries: 10
- 主服务改用：
depends_on:<br> db:<br> condition: service_healthy
权限与挂载模式需显式声明
Linux 容器默认以 root 运行，但挂载宿主机目录时，Windows/macOS 的文件系统无 POSIX 权限模型，容易出现 “Permission denied”。
- 开发阶段：对只读配置用
:ro，避免写入冲突；对日志或上传目录，用命名卷代替绑定挂载 - 生产阶段：若必须挂载，可在容器内用
user:指定 UID/GID，或通过docker-compose.override.yml在不同环境覆盖权限设置 - 不要依赖宿主机当前用户的 UID —— macOS 和 WSL2 的默认 UID 往往是 1000，但 Windows Docker Desktop 内部是虚拟机，UID 映射不同
