README

kimi/storage 是一个面向 ThinkPHP8 的存储管理库，支持本地、阿里云 OSS、七牛云、腾讯云 COS、S3 兼容对象存储，保留 Storage::disk()、Storage::uploadFile()、uploadBase64()、uploadServerFile() 等静态调用方式。

功能支持

存储驱动	表单文件上传	Base64 上传	服务端文件上传
本地 local	✅	✅	✅
阿里云 OSS	✅	✅	✅
七牛云 qiniu	✅	✅	✅
腾讯云 COS	✅	✅	✅
S3 兼容存储	✅	✅	✅

环境要求

PHP >= 8.0
ThinkPHP >= 8.0

安装

composer require kimi/storage

发布配置文件：

php think service:discover
php think vendor:publish

配置文件发布后位于：

config/kimi_storage.php

基本使用

上传当前请求里的表单文件，默认使用 config/kimi_storage.php 中的 default 驱动：

<?php

use Kimi\Storage\Storage;

// 上传 HTTP 表单文件，支持单文件、多文件和嵌套文件字段
$result = Storage::uploadFile();

指定存储驱动：

<?php

use Kimi\Storage\Storage;

// 指定本地驱动上传表单文件
$result = Storage::disk('local')->uploadFile();

// 也兼容数字模式：1 local、2 oss、3 qiniu、4 cos、5 s3
$result = Storage::disk(1)->uploadFile();

上传 Base64 内容：

<?php

use Kimi\Storage\Storage;

// 第二个参数传 false，表示不从当前 HTTP 请求读取上传文件
$result = Storage::disk('local', false)->uploadBase64($base64, 'png');

上传服务器本地文件：

<?php

use Kimi\Storage\Storage;

// 服务端文件上传适合导出文件、临时文件转存等场景
$filePath = root_path() . 'runtime/storage/demo.xlsx';
$result = Storage::disk(Storage::MODE_LOCAL, false)->uploadServerFile($filePath);

配置示例

<?php

use Kimi\Storage\Adapter\LocalAdapter;
use Kimi\Storage\Adapter\OssAdapter;

return [
    // 默认存储驱动，支持 local、oss、qiniu、cos、s3
    'default' => 'local',

    // 文件命名 hash 算法
    'algo' => 'sha1',

    // 单文件大小限制，单位 Byte
    'single_limit' => 1024 * 1024 * 200,

    // 单次请求总文件大小限制，单位 Byte
    'total_limit' => 1024 * 1024 * 200,

    // 单次请求文件数量限制
    'nums' => 10,

    // 扩展名白名单，留空表示不启用白名单
    'include' => [],

    // 扩展名黑名单，include 不为空时不生效
    'exclude' => [],

    // 各存储磁盘配置
    'disks' => [
        'local' => [
            'adapter' => LocalAdapter::class,
            'root' => public_path() . 'storage',
            'path_prefix' => 'public/storage',
            'dirname' => date('Ymd'),
            'domain' => '',
            'uri' => '/storage',
        ],

        'oss' => [
            'adapter' => OssAdapter::class,
            'accessKeyId' => env('OSS_ACCESS_KEY_ID', ''),
            'accessKeySecret' => env('OSS_ACCESS_KEY_SECRET', ''),
            'bucket' => env('OSS_BUCKET', ''),
            'dirname' => 'storage',
            'domain' => env('OSS_DOMAIN', ''),
            'endpoint' => env('OSS_ENDPOINT', ''),
        ],
    ],
];

返回字段

{
  "key": "file",
  "origin_name": "demo.xlsx",
  "save_name": "03414c9bdaf7a38148742c87b96b8167.xlsx",
  "save_path": "public/storage/20260825/03414c9bdaf7a38148742c87b96b8167.xlsx",
  "url": "/storage/20260825/03414c9bdaf7a38148742c87b96b8167.xlsx",
  "unique_id": "03414c9bdaf7a38148742c87b96b8167",
  "size": 15050,
  "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "extension": "xlsx"
}

字段	描述
key	表单文件字段名，非表单上传时没有该字段
origin_name	原始文件名
save_name	保存文件名
save_path	保存路径，本地驱动包含 `path_prefix`，云驱动为对象路径
url	访问地址
unique_id	文件唯一标识，默认由 hash 生成
size	文件大小，单位 Byte
mime_type	文件 MIME 类型
extension	文件扩展名

上传失败会抛出 Kimi\Storage\Exception\StorageException。

云存储 SDK

云存储 SDK 是可选依赖，只在使用对应驱动时安装：

# 阿里云 OSS
composer require aliyuncs/oss-sdk-php

# 七牛云
composer require qiniu/php-sdk

# 腾讯云 COS
composer require qcloud/cos-sdk-v5

# S3 兼容对象存储
composer require aws/aws-sdk-php

运行时配置

单元测试或特殊业务场景可以通过运行时配置覆盖文件配置：

<?php

use Kimi\Storage\Storage;

// 动态设置完整配置，会和包内默认配置递归合并
Storage::setConfig([
    'default' => 'local',
    'disks' => [
        'local' => [
            'root' => root_path() . 'runtime/storage',
            'path_prefix' => 'runtime/storage',
            'uri' => '/storage',
        ],
    ],
]);

// 清空运行时配置，恢复读取 ThinkPHP 配置
Storage::clearConfig();

开发验证

composer validate
vendor/bin/phpunit
vendor/bin/phpstan analyse src
vendor/bin/php-cs-fixer fix src

kimi / storage

Maintainers

Package info

Statistics

Security