ThinkPHP 8.0 文件上传 OSS 整合教程【保姆级】-ThinkPHP-PHP中文网

thinkphp 8.0整合阿里云oss上传应采用“配置驱动+安全上传+统一调用”模式，通过filesystem驱动配置oss磁盘、环境变量管理凭证、白名单校验与唯一路径生成实现安全可控的文件上传。

thinkphp 8.0 文件上传 oss 整合教程【保姆级】

ThinkPHP 8.0 整合阿里云 OSS 上传，核心是“配置驱动 + 安全上传 + 统一调用”。不推荐手动拼接 SDK 实例或硬编码凭证，应优先使用框架原生的 filesystem 驱动机制，既简洁又利于维护和切换存储后端。

一、安装 SDK 并配置环境变量

在项目根目录执行：

composer require aliyuncs/oss-sdk-php
确保 PHP 已启用 curl 和 openssl 扩展（OSS 通信必需）
在 .env 文件中添加 OSS 凭证（严禁写死在代码里）：

OSS_ACCESS_ID=your-access-key-id
OSS_ACCESS_KEY=your-access-key-secret
OSS_BUCKET=your-bucket-name
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_CDN_DOMAIN=https://cdn.yourdomain.com

Endpoint 请按你创建 Bucket 的实际地域填写，如北京填 oss-cn-beijing.aliyuncs.com；若开启 CDN 加速，可填加速域名提升访问速度。

二、启用并配置 OSS 文件系统磁盘

编辑 config/filesystem.php，在 'disks' 数组中加入：

'oss' => [
    'type' => 'oss',
    'access_id' => env('OSS_ACCESS_ID'),
    'access_key' => env('OSS_ACCESS_KEY'),
    'bucket' => env('OSS_BUCKET'),
    'endpoint' => env('OSS_ENDPOINT'),
    'cdn_domain' => env('OSS_CDN_DOMAIN'),
    'ssl' => true,
],

同时将 'default' 设为 'oss'，或保留为 'local'，按需在业务中显式指定磁盘：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

全局默认走 OSS：'default' => 'oss'
局部使用 OSS：Storage::disk('oss')->put(...)

三、控制器中安全上传文件

上传逻辑要兼顾校验、重命名与路径隔离。以下是一个典型示例（支持图片/文档等常见类型）：

use think\facade\Storage;
use think\Request;

public function upload(Request $request)
{
    $file = $request->file('file');
    if (!$file) {
        return json(['code' => 400, 'msg' => '未检测到文件']);
    }

    // 白名单校验（扩展名 + MIME）
    $ext = $file->getExtension();
    $allowed = ['jpg', 'jpeg', 'png', 'gif', 'pdf', 'docx', 'xlsx'];
    if (!in_array(strtolower($ext), $allowed)) {
        return json(['code' => 400, 'msg' => '不支持的文件类型']);
    }

    // 生成唯一对象 Key：避免路径遍历，不直接用原始名
    $dateDir = date('Ym/d');
    $safeName = uniqid() . '.' . $ext;
    $objectKey = "uploads/{$dateDir}/{$safeName}";

    try {
        // 上传至 OSS，并返回可访问 URL
        $result = Storage::disk('oss')->put($objectKey, $file->getStream());
        if ($result) {
            $url = Storage::disk('oss')->url($objectKey);
            return json(['code' => 200, 'msg' => '上传成功', 'data' => ['url' => $url, 'path' => $objectKey]]);
        }
    } catch (\Exception $e) {
        return json(['code' => 500, 'msg' => 'OSS 上传失败：' . $e->getMessage()]);
    }
}

关键点说明：