Laravel Docker环境下Storage软链接指向本地目录的问题解决

核心问题 #

本地执行php artisan storage:link会生成绝对路径软链接，指向本地的项目目录，但Docker容器内的项目路径是/var/www/html，无法识别本地路径，导致资源404；而容器内执行命令生成的绝对路径又不兼容本地环境。

最优解决方案 #

利用Laravel 8.75+（含Laravel 9）支持的--relative参数，生成相对路径软链接，一次创建即可兼容本地与Docker环境：

1. 先删除已存在的错误软链接（本地执行即可，容器内挂载的目录会同步更新）：

   rm public/storage
   

2. 在项目根目录执行带--relative参数的Artisan命令：

   php artisan storage:link --relative
   

生成的软链接为相对路径../storage/app/public，无论在本地环境还是Docker容器内，都会基于当前public目录的上级目录解析路径，确保资源能正确加载。

验证方法 #

• 本地查看public/storage的链接属性：

  ls -l public/storage
  

  输出应为：storage -> ../storage/app/public

• 进入Docker容器查看（可选，确认兼容性）：

  ./vendor/bin/sail exec laravel.test ls -l public/storage
  

  输出同样为相对路径，容器内可正常解析到/var/www/html/storage/app/public

替代方案（低版本Laravel兼容） #

如果你的Laravel版本低于8.75，无法使用--relative参数，可手动创建相对路径软链接：

cd public
ln -s ../storage/app/public storage

内容的提问来源于stack exchange，提问作者ajp357