应使用环境变量动态注入uid/gid：在docker-compose.yml中配置user: "${uid:-1001}:${gid:-1001}"，并确保宿主机shell导出export uid=$(id -u)和export gid=$(id -g)，同时配合composer install --uid=${uid} --gid=${gid}确保三者对齐。
docker-compose.yml 里怎么传宿主机 UID/GID
关键不是“写死数字”，而是让 docker-compose 在启动时自动读取当前用户的 UID 和 GID。硬编码 user: "1001:1001" 会导致团队成员在不同机器上构建失败——有人是 1000，有人是 501（macOS），还有人可能用 root。
正确做法是用环境变量注入：
- 在
docker-compose.yml的 service 下写：user: "${UID:-1001}:${GID:-1001}" - 确保宿主机 shell 启动时已导出这两个变量，比如加到
~/.bashrc或~/.zshrc：export UID=$(id -u)和export GID=$(id -g) - macOS 用户注意：Docker Desktop 默认不向容器传递环境变量，需在 Docker Desktop → Settings → General 中勾选 “Use the Docker CLI from the terminal”
这样每次 docker-compose up 都会用你当前用户的实际 UID/GID 启动容器，vendor/ 目录创建时属主自然匹配。
composer install --uid 和 --gid 参数必须配对使用
Composer 2.2+ 支持直接控制生成文件的属主，但这个参数只影响 vendor/、composer.lock、缓存目录等由 Composer 创建的文件，**不改变 PHP 进程本身的运行用户**。所以它必须和容器的 --user 或 user: 配置配合，否则权限仍会错位。
- 命令行调用示例：
composer install --uid=1001 --gid=1001 - 在
docker-compose.yml的command:中写：command: composer install --uid=${UID:-1001} --gid=${GID:-1001} - 如果漏掉
--gid，某些 Linux 发行版下chown会失败，报错类似：chown: invalid group: ‘1001’ - 该参数对
composer update同样有效，但对已存在的vendor/不做递归修复——得先rm -rf vendor/ composer.lock再重装
别用 chmod -R 777 vendor/ 临时糊弄
看到 Permission denied 就跑 chmod -R 777 vendor/ 是最典型的“表面解决”，后果比问题本身更麻烦：
- Composer 下次执行
update时可能拒绝覆盖文件，因为权限异常触发校验失败 -
vendor/里的文件时间戳和属主混乱，导致git status显示大量“权限变更”，污染 git 工作区 - CI 流水线（如 GitHub Actions）跑在干净容器里，没这问题；但你本地修了权限后提交了修改过的
vendor/，CI 构建反而会失败 - 真正要 fix 的是“谁创建了这些文件”，而不是“怎么让谁都写得进去”
挂载卷时避免 vendor/ 被覆盖或冲突
开发中常把整个项目目录挂进容器，比如 volumes: - .:/app。但如果宿主机已有 vendor/（尤其是属主是 root 或其他 UID），它会被直接挂进容器，覆盖容器内 Composer 正确生成的版本。
- 推荐在
.dockerignore里加上vendor/，防止宿主机的vendor/被复制进镜像层 - 开发时用命名卷隔离缓存：
volumes: - composer_cache:/root/.composer/cache，但不要挂载vendor/到宿主机 - 如果非要共享
vendor/（比如 IDE 索引需要），用命名卷 + 正确 UID 初始化：docker run --rm -v vendor_cache:/app/vendor --user 1001:1001 php:8.3-cli composer install --uid=1001 --gid=1001
复杂点在于：UID/GID 必须在宿主机、容器运行时、Composer 三个层面同时对齐，少一个环节就会回退到权限报错。最容易被忽略的是 macOS 用户忘记开启 Docker CLI 集成，或者团队成员没同步 export UID 这一行 shell 配置。
