szkp-map-service/app/Http/Controllers/Concerns/EnsuresPublicDiskWritable.php

<?php

namespace App\Http\Controllers\Concerns;

use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Log;
use Throwable;

trait EnsuresPublicDiskWritable
{
    /**
     * 线上常见：storage/app/public 对 PHP-FPM 用户不可写，本地开发用户有权限故正常。
     */
    protected function ensurePublicDiskReady(): ?JsonResponse
    {
        $dir = storage_path('app/public');
        try {
            if (!is_dir($dir)) {
                mkdir($dir, 0775, true);
            }
        } catch (Throwable $e) {
            report($e);

            return response()->json([
                'message' => '无法创建存储目录 storage/app/public',
                'detail' => config('app.debug') ? $e->getMessage() : null,
            ], 500);
        }

        if (!is_writable($dir)) {
            Log::error('upload_public_dir_not_writable', ['path' => $dir]);

            return response()->json([
                'message' => '存储目录不可写，请在线上为 PHP 运行用户开放 storage 与 bootstrap/cache 写权限',
                'hint' => '示例：chmod -R ug+rwx storage bootstrap/cache && chown -R www-data:www-data storage bootstrap/cache（用户以实际 php-fpm 用户为准）',
            ], 500);
        }

        return null;
    }
}