env()函数必须在filesystem.php中显式调用，否则.env中的UPLOAD_ROOT等变量不会生效；需在disks配置的root、url等字段使用env()并配合public_path()等函数，且修改后须执行php think clear:config清除配置缓存。
env() 函数必须在 upload.php 配置文件中显式调用
ThinkPHP 不会自动把 .env 里的变量塞进上传配置——哪怕你写了 UPLOAD_PATH=/uploads，只要 config/filesystem.php（或 config/upload.php，取决于你是否自定义）里没调用 env('UPLOAD_PATH', 'runtime/upload')，这个值就永远不会生效。
常见错误是只改 .env，然后在控制器里用 env('UPLOAD_PATH') 测试返回正常，就以为上传目录已切换。其实这只是读到了环境变量，但框架的上传驱动初始化时根本没用它。
- 确保你在
config/filesystem.php的'disks' => ['public' => [...]]或自定义上传磁盘配置中，对路径字段（如'root'、'url'）全部使用env() - 例如：
'root' => env('UPLOAD_ROOT', runtime_path('upload'))，不要写死'root' => '/var/www/html/public/uploads' - 第二个参数推荐用
runtime_path('upload')或public_path('uploads')这类动态路径函数，比硬编码字符串更安全
APP_ENV 和 UPLOAD_DISK 要配合使用，不能只靠 .env 切换目录
上传目录常和「多环境行为」强相关：开发时存本地 public/uploads，生产可能走 OSS 或 S3。这时候光靠 UPLOAD_ROOT 环境变量不够，得结合磁盘驱动切换。
- 在
config/filesystem.php中，用env('APP_ENV', 'dev')判断当前环境，再决定启用哪个磁盘： 'default' => env('APP_ENV') === 'prod' ? 'oss' : 'public'- 确保
config/prod/filesystem.php里重写了'disks.oss'的完整配置（含endpoint、access_key等），而不仅靠.env - 如果用了自定义上传配置文件（如
config/upload.php），也要保证它被filesystem.php加载或被框架识别
权限与路径拼接容易出错，尤其在容器或 Nginx 下
.env 里写的路径，最终会被 PHP 拼接到物理文件系统。若格式或权限不对，上传会静默失败或报 mkdir(): Permission denied。
-
UPLOAD_ROOT值**不能以/开头写绝对路径**（除非你明确知道 Web 进程用户能写该位置），推荐用相对路径 +public_path()或runtime_path() - 例如：
UPLOAD_ROOT=uploads✅，UPLOAD_ROOT=/data/uploads❌（容器内往往无权写/data） - Linux/macOS 下确认 Web 用户（如
www-data或nginx）对目标目录有rwx权限；Docker 镜像中需在启动前RUN chmod -R 755 /var/www/html/public/uploads - Nginx 配置里若加了
alias或重写了location /uploads，要确保其指向和UPLOAD_ROOT解析后的真实路径一致，否则 URL 可访问但 PHP 写入失败
修改后必须清配置缓存，否则 upload.php 里的 env() 仍用旧值
ThinkPHP 把所有配置（包括 env() 执行结果）合并缓存到 runtime/config.php。不清理，改十次 .env 也没用。
- 执行：
php think clear:config（TP6.0+）或php think optimize:config（重建全量缓存） - 也可直接删掉：
rm -f runtime/config.php - CI/CD 流程中务必把清缓存步骤加进部署脚本，否则上线后上传功能大概率异常
- 验证是否生效：在控制器里打印
config('filesystems.disks.public.root')，看输出是否是你期望的路径，而不是默认值
真正卡住人的地方，往往不是不会写 env('UPLOAD_ROOT')，而是没意识到：路径值要经过 PHP 拼接、Web 用户权限校验、Nginx 路由映射、以及缓存机制四层过滤。漏掉任何一层，上传目录就“看起来配了，实际不走”。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
