当 docker 容器以非 root 用户（如 `1000:1000`）运行但未定义对应系统用户时，`~` 展开失败、`whoami` 报错、`php artisan tinker` 因无法写入 `~/.config/psysh` 而崩溃。根本解法不是强行创建用户家目录，而是通过环境变量重定向配置路径。
在你当前的 docker-compose.yml 中，php 服务通过 user: "${HOST_UID}:${HOST_GID}" 以宿主机用户 ID 运行，这虽提升了安全性（避免 root 权限），但 PHP 容器镜像（php:8.0-fpm）默认不包含 UID 1000 对应的系统用户——既无 /etc/passwd 条目，也无 /home/clarg（或类似）目录。因此：
- whoami 失败：glibc 无法反查 UID → 用户名；
- ls ~ 报错：shell 尝试展开 ~ 到不存在的家目录；
- php artisan tinker 崩溃：PsySH 默认使用 XDG_CONFIG_HOME（若未设则 fallback 至 $HOME/.config/psysh），而 $HOME 为空或 /，导致写入 /.config/psysh 被拒绝（权限 + 只读根文件系统）。
✅ 推荐方案：显式设置 XDG_CONFIG_HOME
无需修改基础镜像或手动创建用户，只需为 PHP 容器指定一个容器内可写的、与项目解耦的配置目录。例如，在 docker-compose.yml 的 php 服务中添加环境变量：
php:
build:
context: ./docker
dockerfile: Dockerfile-php
user: "${HOST_UID}:${HOST_GID}"
environment:
XDG_CONFIG_HOME: /var/www/.config # ✅ 关键：指向项目内可写路径
volumes:
- "${PROJECT_DIR}:/var/www/html"
- ./docker/php/php.ini:/usr/local/etc/php/php.ini
working_dir: /var/www/html
networks:
- laravel? 为什么选 /var/www/.config？ /var/www/html 是 Web 根目录，不宜混放配置； /var/www 是挂载卷的父目录，确保其在容器内存在且可写（Docker 默认创建该路径，且 user: "1000:1000" 对其有写权限）； .config 是 XDG 标准规范路径，PsySH、Composer 等工具均原生支持。
? 进阶建议（可选）
若需更彻底地兼容开发体验（如 composer global、npm config），可一并设置其他 XDG 环境变量：
environment: XDG_CONFIG_HOME: /var/www/.config XDG_CACHE_HOME: /var/www/.cache XDG_DATA_HOME: /var/www/.local/share
并在 Dockerfile-php 中确保目录初始化（防首次运行失败）：
# 在 Dockerfile-php 末尾添加
RUN mkdir -p /var/www/.config /var/www/.cache /var/www/.local/share \
&& chown -R ${HOST_UID}:${HOST_GID} /var/www/.config /var/www/.cache /var/www/.local/share⚠️ 注意事项
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 不要尝试在 Dockerfile 中用 useradd -u 1000 clarg 创建用户：UID 可能因环境变化（CI/CD、不同开发者）而冲突，违背镜像可移植性原则；
- 避免将 XDG_CONFIG_HOME 设为 /tmp：临时目录可能被清理，且部分工具对 tmpfs 行为敏感；
- 若使用 docker-compose exec php --user root ... 临时调试，需注意 root 用户下 XDG_CONFIG_HOME 仍需显式设置，否则问题复现。
✅ 验证是否生效：
docker-compose exec php sh -c 'echo $XDG_CONFIG_HOME && ls -la /var/www/.config' # 应输出：/var/www/.config，并显示空目录（首次运行后 PsySH 会自动创建子目录） docker-compose exec php php artisan tinker # 此时应正常启动
通过环境变量接管 XDG 路径，你既保持了容器的安全非 root 运行模式，又规避了系统用户映射的复杂性，是 Docker 化 PHP 开发的标准实践。
