文件存储
简介
得益于 Frank de Jonge 出色的 Flysystem PHP 包，Laravel 提供了强大的文件系统抽象。Laravel 的 Flysystem 集成提供了用于操作本地文件系统、SFTP 以及 Amazon S3 的简易驱动。更棒的是，由于各系统的 API 保持一致，在本地开发机与生产服务器之间切换这些存储选项非常简单。
配置
Laravel 的文件系统配置文件位于 config/filesystems.php。你可以在该文件中配置所有文件系统「磁盘」。每个磁盘代表特定的存储驱动与存储位置。配置文件中已包含各受支持驱动的示例配置，你可按自己的存储偏好与凭证进行修改。
local 驱动用于操作运行 Laravel 应用的服务器上的本地文件，而 sftp 存储驱动用于基于 SSH 密钥的 FTP。s3 驱动用于写入 Amazon 的 S3 云存储服务。
INFO
你可以按需配置任意数量的磁盘，甚至可以有多个使用相同驱动的磁盘。
本地驱动
使用 local 驱动时，所有文件操作都相对于 filesystems 配置文件中定义的 root 目录。默认情况下，该值设置为 storage/app/private 目录。因此，下面的方法会写入 storage/app/private/example.txt：
use Illuminate\Support\Facades\Storage;
Storage::disk('local')->put('example.txt', 'Contents');Public 磁盘
应用 filesystems 配置文件中包含的 public 磁盘，用于存放需要公开访问的文件。默认情况下，public 磁盘使用 local 驱动，并将文件存储在 storage/app/public。
若 public 磁盘使用 local 驱动，并希望这些文件可通过 Web 访问，应创建从源目录 storage/app/public 到目标目录 public/storage 的符号链接：
要创建符号链接，可以使用 storage:link Artisan 命令：
php artisan storage:link文件存储完成且符号链接创建后，你可以使用 asset 辅助函数为这些文件生成 URL：
echo asset('storage/file.txt');你可以在 filesystems 配置文件中配置额外的符号链接。运行 storage:link 命令时，会创建所有已配置的链接：
'links' => [
public_path('storage') => storage_path('app/public'),
public_path('images') => storage_path('app/images'),
],可使用 storage:unlink 命令删除已配置的符号链接：
php artisan storage:unlink驱动前置要求
S3 驱动配置
使用 S3 驱动之前，需要通过 Composer 包管理器安装 Flysystem S3 包：
composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependenciesconfig/filesystems.php 配置文件中包含 S3 磁盘的配置数组。通常，你应使用下列环境变量配置 S3 信息与凭证，这些变量由 config/filesystems.php 配置文件引用：
AWS_ACCESS_KEY_ID=<your-key-id>
AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=<your-bucket-name>
AWS_USE_PATH_STYLE_ENDPOINT=false为方便起见，这些环境变量与 AWS CLI 使用的命名约定一致。
FTP 驱动配置
使用 FTP 驱动之前，需要通过 Composer 包管理器安装 Flysystem FTP 包：
composer require league/flysystem-ftp "^3.0"Laravel 的 Flysystem 集成与 FTP 配合良好；不过，框架默认的 config/filesystems.php 配置文件中未包含示例配置。若需要配置 FTP 文件系统，可使用下面的配置示例：
'ftp' => [
'driver' => 'ftp',
'host' => env('FTP_HOST'),
'username' => env('FTP_USERNAME'),
'password' => env('FTP_PASSWORD'),
// Optional FTP Settings...
// 'port' => env('FTP_PORT', 21),
// 'root' => env('FTP_ROOT'),
// 'passive' => true,
// 'ssl' => true,
// 'timeout' => 30,
],SFTP 驱动配置
使用 SFTP 驱动之前，需要通过 Composer 包管理器安装 Flysystem SFTP 包：
composer require league/flysystem-sftp-v3 "^3.0"Laravel 的 Flysystem 集成与 SFTP 配合良好；不过，框架默认的 config/filesystems.php 配置文件中未包含示例配置。若需要配置 SFTP 文件系统，可使用下面的配置示例：
'sftp' => [
'driver' => 'sftp',
'host' => env('SFTP_HOST'),
// Settings for basic authentication...
'username' => env('SFTP_USERNAME'),
'password' => env('SFTP_PASSWORD'),
// Settings for SSH key-based authentication with encryption password...
'privateKey' => env('SFTP_PRIVATE_KEY'),
'passphrase' => env('SFTP_PASSPHRASE'),
// Settings for file / directory permissions...
'visibility' => 'private', // `private` = 0600, `public` = 0644
'directory_visibility' => 'private', // `private` = 0700, `public` = 0755
// Optional SFTP Settings...
// 'hostFingerprint' => env('SFTP_HOST_FINGERPRINT'),
// 'maxTries' => 4,
// 'passphrase' => env('SFTP_PASSPHRASE'),
// 'port' => env('SFTP_PORT', 22),
// 'root' => env('SFTP_ROOT', ''),
// 'timeout' => 30,
// 'useAgent' => true,
],作用域与只读文件系统
作用域磁盘允许你定义一个文件系统，其中所有路径都会自动加上给定的路径前缀。创建作用域文件系统磁盘之前，需要通过 Composer 包管理器安装额外的 Flysystem 包：
composer require league/flysystem-path-prefixing "^3.0"你可以通过定义使用 scoped 驱动的磁盘，为任意现有文件系统磁盘创建带路径作用域的实例。例如，可以创建一个磁盘，将现有 s3 磁盘限定到特定路径前缀，之后使用该作用域磁盘的所有文件操作都会使用指定前缀：
's3-videos' => [
'driver' => 'scoped',
'disk' => 's3',
'prefix' => 'path/to/videos',
],「只读」磁盘允许你创建不允许写入操作的文件系统磁盘。使用 read-only 配置选项之前，需要通过 Composer 包管理器安装额外的 Flysystem 包：
composer require league/flysystem-read-only "^3.0"接下来，你可以在一个或多个磁盘的配置数组中加入 read-only 配置选项：
's3-videos' => [
'driver' => 's3',
// ...
'read-only' => true,
],兼容 Amazon S3 的文件系统
默认情况下，应用的 filesystems 配置文件已包含 s3 磁盘配置。除了用该磁盘与 Amazon S3 交互外，你还可以用它与任意兼容 S3 的文件存储服务交互，例如 RustFS、DigitalOcean Spaces、Vultr Object Storage、Cloudflare R2 或 Hetzner Cloud Storage。
通常，在将磁盘凭证更新为你计划使用的服务凭证后，只需更新 endpoint 配置选项的值。该选项的值通常通过 AWS_ENDPOINT 环境变量定义：
'endpoint' => env('AWS_ENDPOINT', 'https://rustfs:9000'),获取磁盘实例
可使用 Storage facade 与任意已配置的磁盘交互。例如，你可以在 facade 上使用 put 方法将头像存储到默认磁盘。若在未先调用 disk 方法的情况下调用 Storage facade 上的方法，该方法会自动作用于默认磁盘：
use Illuminate\Support\Facades\Storage;
Storage::put('avatars/1', $content);若应用需要与多个磁盘交互，可在 Storage facade 上使用 disk 方法操作特定磁盘上的文件：
Storage::disk('s3')->put('avatars/1', $content);按需磁盘
有时你可能希望在运行时用给定配置创建磁盘，而该配置并未实际出现在应用的 filesystems 配置文件中。为此，可以将配置数组传给 Storage facade 的 build 方法：
use Illuminate\Support\Facades\Storage;
$disk = Storage::build([
'driver' => 'local',
'root' => '/path/to/root',
]);
$disk->put('image.jpg', $content);检索文件
可使用 get 方法检索文件内容。该方法会返回文件的原始字符串内容。请记住，所有文件路径都应相对于磁盘的「根」位置指定：
$contents = Storage::get('file.jpg');若要检索的文件包含 JSON，可使用 json 方法检索文件并解码其内容：
$orders = Storage::json('orders.json');可使用 exists 方法判断磁盘上是否存在某个文件：
if (Storage::disk('s3')->exists('file.jpg')) {
// ...
}可使用 missing 方法判断磁盘上是否缺少某个文件：
if (Storage::disk('s3')->missing('file.jpg')) {
// ...
}下载文件
可使用 download 方法生成强制用户浏览器下载给定路径文件的响应。download 方法接受文件名作为第二个参数，该参数决定下载用户看到的文件名。最后，你还可以将 HTTP 头数组作为第三个参数传入：
return Storage::download('file.jpg');
return Storage::download('file.jpg', $name, $headers);文件 URL
你可以使用 url 方法获取给定文件的 URL。若使用 local 驱动，通常只会在给定路径前加上 /storage，并返回该文件的相对 URL。若使用 s3 驱动，则会返回完整的远程 URL：
use Illuminate\Support\Facades\Storage;
$url = Storage::url('file.jpg');使用 local 驱动时，所有应公开访问的文件都应放在 storage/app/public 目录中。此外，你还应在 public/storage 创建符号链接，指向 storage/app/public 目录。
WARNING
使用 local 驱动时，url 的返回值不会进行 URL 编码。因此，我们建议始终使用能生成合法 URL 的名称存储文件。
自定义 URL 主机
若要修改使用 Storage facade 生成的 URL 主机，可在磁盘配置数组中添加或更改 url 选项：
'public' => [
'driver' => 'local',
'root' => storage_path('app/public'),
'url' => env('APP_URL').'/storage',
'visibility' => 'public',
'throw' => false,
],临时 URL
使用 temporaryUrl 方法，你可以为使用 local 与 s3 驱动存储的文件创建临时 URL。该方法接受路径以及指定 URL 过期时间的 DateTime 实例：
use Illuminate\Support\Facades\Storage;
$url = Storage::temporaryUrl(
'file.jpg', now()->plus(minutes: 5)
);启用本地临时 URL
若你在 local 驱动引入临时 URL 支持之前就开始开发应用，可能需要启用本地临时 URL。为此，请在 config/filesystems.php 配置文件中的 local 磁盘配置数组里添加 serve 选项：
'local' => [
'driver' => 'local',
'root' => storage_path('app/private'),
'serve' => true, // [tl! add]
'throw' => false,
],S3 请求参数
若需要指定额外的 S3 请求参数，可将请求参数数组作为第三个参数传给 temporaryUrl 方法：
$url = Storage::temporaryUrl(
'file.jpg',
now()->plus(minutes: 5),
[
'ResponseContentType' => 'application/octet-stream',
'ResponseContentDisposition' => 'attachment; filename=file2.jpg',
]
);自定义临时 URL
若需要自定义特定存储磁盘创建临时 URL 的方式，可以使用 buildTemporaryUrlsUsing 方法。例如，当你有一个控制器用于下载通常不支持临时 URL 的磁盘上存储的文件时，这会很有用。通常，该方法应在服务提供者的 boot 方法中调用：
<?php
namespace App\Providers;
use DateTime;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Facades\URL;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Storage::disk('local')->buildTemporaryUrlsUsing(
function (string $path, DateTime $expiration, array $options) {
return URL::temporarySignedRoute(
'files.download',
$expiration,
array_merge($options, ['path' => $path])
);
}
);
}
}临时上传 URL
WARNING
生成临时上传 URL 的能力仅由 s3 与 local 驱动支持。
若需要生成可从客户端应用直接上传文件的临时 URL，可使用 temporaryUploadUrl 方法。该方法接受路径以及指定 URL 过期时间的 DateTime 实例。temporaryUploadUrl 方法返回关联数组，可解构为上传 URL 以及上传请求应包含的请求头：
use Illuminate\Support\Facades\Storage;
['url' => $url, 'headers' => $headers] = Storage::temporaryUploadUrl(
'file.jpg', now()->plus(minutes: 5)
);该方法主要用于无服务器环境，这类环境要求客户端应用直接将文件上传到 Amazon S3 等云存储系统。
文件元数据
除了读写文件外，Laravel 还能提供关于文件本身的信息。例如，可使用 size 方法获取文件大小（以字节为单位）：
use Illuminate\Support\Facades\Storage;
$size = Storage::size('file.jpg');lastModified 方法返回文件最后一次修改时的 UNIX 时间戳：
$time = Storage::lastModified('file.jpg');可通过 mimeType 方法获取给定文件的 MIME 类型：
$mime = Storage::mimeType('file.jpg');文件路径
你可以使用 path 方法获取给定文件的路径。若使用 local 驱动，将返回文件的绝对路径。若使用 s3 驱动，该方法将返回文件在 S3 存储桶中的相对路径：
use Illuminate\Support\Facades\Storage;
$path = Storage::path('file.jpg');存储文件
可使用 put 方法将文件内容存储到磁盘上。你也可以向 put 方法传入 PHP resource，它会使用 Flysystem 底层的流支持。请记住，所有文件路径都应相对于为磁盘配置的「根」位置指定：
use Illuminate\Support\Facades\Storage;
Storage::put('file.jpg', $contents);
Storage::put('file.jpg', $resource);写入失败
若 put 方法（或其他「写入」操作）无法将文件写入磁盘，将返回 false：
if (! Storage::put('file.jpg', $contents)) {
// The file could not be written to disk...
}若需要，你可以在文件系统磁盘的配置数组中定义 throw 选项。当该选项定义为 true 时，诸如 put 等「写入」方法在写入失败时会抛出 League\Flysystem\UnableToWriteFile 实例：
'public' => [
'driver' => 'local',
// ...
'throw' => true,
],在文件开头与末尾写入
prepend 与 append 方法允许你向文件开头或末尾写入内容：
Storage::prepend('file.log', 'Prepended Text');
Storage::append('file.log', 'Appended Text');复制与移动文件
可使用 copy 方法将现有文件复制到磁盘上的新位置，而 move 方法可用于重命名或将现有文件移动到新位置：
Storage::copy('old/file.jpg', 'new/file.jpg');
Storage::move('old/file.jpg', 'new/file.jpg');自动流式传输
将文件以流的方式写入存储可显著降低内存占用。若希望 Laravel 自动管理将给定文件流式传输到存储位置，可使用 putFile 或 putFileAs 方法。该方法接受 Illuminate\Http\File 或 Illuminate\Http\UploadedFile 实例，并会自动将文件流式传输到目标位置：
use Illuminate\Http\File;
use Illuminate\Support\Facades\Storage;
// Automatically generate a unique ID for filename...
$path = Storage::putFile('photos', new File('/path/to/photo'));
// Manually specify a filename...
$path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');关于 putFile 方法有几点需要注意。注意我们只指定了目录名，而没有指定文件名。默认情况下，putFile 方法会生成一个唯一 ID 作为文件名。文件扩展名将通过检查文件的 MIME 类型确定。putFile 方法会返回文件路径，因此你可以将包含生成文件名的路径存入数据库。
putFile 与 putFileAs 方法还接受一个参数，用于指定所存文件的「可见性」。若你将文件存储在 Amazon S3 等云磁盘上，并希望文件可通过生成的 URL 公开访问，这一点尤其有用：
Storage::putFile('photos', new File('/path/to/photo'), 'public');文件上传
在 Web 应用中，存储文件最常见的场景之一是保存用户上传的照片、文档等文件。Laravel 通过上传文件实例上的 store 方法，让存储上传文件变得非常简单。调用 store 方法时传入希望存储上传文件的路径即可：
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class UserAvatarController extends Controller
{
/**
* Update the avatar for the user.
*/
public function update(Request $request): string
{
$path = $request->file('avatar')->store('avatars');
return $path;
}
}关于这个示例有几点需要注意。注意我们只指定了目录名，而没有指定文件名。默认情况下，store 方法会生成一个唯一 ID 作为文件名。文件扩展名将通过检查文件的 MIME 类型确定。store 方法会返回文件路径，因此你可以将包含生成文件名的路径存入数据库。
你也可以在 Storage facade 上调用 putFile 方法，执行与上面示例相同的文件存储操作：
$path = Storage::putFile('avatars', $request->file('avatar'));指定文件名
若不想为存储的文件自动分配文件名，可使用 storeAs 方法，它接收路径、文件名以及（可选的）磁盘作为参数：
$path = $request->file('avatar')->storeAs(
'avatars', $request->user()->id
);你也可以在 Storage facade 上使用 putFileAs 方法，执行与上面示例相同的文件存储操作：
$path = Storage::putFileAs(
'avatars', $request->file('avatar'), $request->user()->id
);WARNING
不可打印与非法的 Unicode 字符会自动从文件路径中移除。因此，在将路径传给 Laravel 的文件存储方法之前，你可能需要先清理文件路径。文件路径会使用 League\Flysystem\WhitespacePathNormalizer::normalizePath 方法进行规范化。
指定磁盘
默认情况下，上传文件的 store 方法会使用默认磁盘。若要指定其他磁盘，请将磁盘名称作为第二个参数传给 store 方法：
$path = $request->file('avatar')->store(
'avatars/'.$request->user()->id, 's3'
);若使用 storeAs 方法，可将磁盘名称作为第三个参数传给该方法：
$path = $request->file('avatar')->storeAs(
'avatars',
$request->user()->id,
's3'
);其他上传文件信息
若要获取上传文件的原始名称与扩展名，可使用 getClientOriginalName 与 getClientOriginalExtension 方法：
$file = $request->file('avatar');
$name = $file->getClientOriginalName();
$extension = $file->getClientOriginalExtension();不过请注意，getClientOriginalName 与 getClientOriginalExtension 方法被认为是不安全的，因为文件名与扩展名可能被恶意用户篡改。因此，通常应优先使用 hashName 与 extension 方法来获取给定上传文件的名称与扩展名：
$file = $request->file('avatar');
$name = $file->hashName(); // Generate a unique, random name...
$extension = $file->extension(); // Determine the file's extension based on the file's MIME type...文件可见性
在 Laravel 的 Flysystem 集成中，「可见性」是跨多平台文件权限的抽象。文件可声明为 public 或 private。当文件声明为 public 时，表示该文件通常应可被他人访问。例如，使用 S3 驱动时，你可以获取 public 文件的 URL。
你可以在通过 put 方法写入文件时设置可见性：
use Illuminate\Support\Facades\Storage;
Storage::put('file.jpg', $contents, 'public');若文件已经存储，可通过 getVisibility 与 setVisibility 方法获取和设置其可见性：
$visibility = Storage::getVisibility('file.jpg');
Storage::setVisibility('file.jpg', 'public');处理上传文件时，可使用 storePublicly 与 storePubliclyAs 方法以 public 可见性存储上传文件：
$path = $request->file('avatar')->storePublicly('avatars', 's3');
$path = $request->file('avatar')->storePubliclyAs(
'avatars',
$request->user()->id,
's3'
);本地文件与可见性
使用 local 驱动时，public 可见性对应目录权限 0755、文件权限 0644。你可以在应用的 filesystems 配置文件中修改权限映射：
'local' => [
'driver' => 'local',
'root' => storage_path('app'),
'permissions' => [
'file' => [
'public' => 0644,
'private' => 0600,
],
'dir' => [
'public' => 0755,
'private' => 0700,
],
],
'throw' => false,
],删除文件
delete 方法接受单个文件名或要删除的文件数组：
use Illuminate\Support\Facades\Storage;
Storage::delete('file.jpg');
Storage::delete(['file.jpg', 'file2.jpg']);如有必要，你可以指定应从哪个磁盘删除文件：
use Illuminate\Support\Facades\Storage;
Storage::disk('s3')->delete('path/file.jpg');目录
获取目录中的所有文件
files 方法返回给定目录中所有文件的数组。若要获取给定目录（含其子目录）中的所有文件列表，可使用 allFiles 方法：
use Illuminate\Support\Facades\Storage;
$files = Storage::files($directory);
$files = Storage::allFiles($directory);获取目录中的所有目录
directories 方法返回给定目录中所有目录的数组。若要获取给定目录（含其子目录）中的所有目录列表，可使用 allDirectories 方法：
$directories = Storage::directories($directory);
$directories = Storage::allDirectories($directory);创建目录
makeDirectory 方法会创建给定目录，包括所需的任何子目录：
Storage::makeDirectory($directory);删除目录
最后，可使用 deleteDirectory 方法删除目录及其所有文件：
Storage::deleteDirectory($directory);测试
Storage facade 的 fake 方法可轻松生成假磁盘，再结合 Illuminate\Http\UploadedFile 类的文件生成工具，可极大简化文件上传测试。例如：
<?php
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
test('albums can be uploaded', function () {
Storage::fake('photos');
$response = $this->json('POST', '/photos', [
UploadedFile::fake()->image('photo1.jpg'),
UploadedFile::fake()->image('photo2.jpg')
]);
// Assert one or more files were stored...
Storage::disk('photos')->assertExists('photo1.jpg');
Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);
// Assert one or more files were not stored...
Storage::disk('photos')->assertMissing('missing.jpg');
Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);
// Assert that the number of files in a given directory matches the expected count...
Storage::disk('photos')->assertCount('/wallpapers', 2);
// Assert that a given directory is empty...
Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
});<?php
namespace Tests\Feature;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use Tests\TestCase;
class ExampleTest extends TestCase
{
public function test_albums_can_be_uploaded(): void
{
Storage::fake('photos');
$response = $this->json('POST', '/photos', [
UploadedFile::fake()->image('photo1.jpg'),
UploadedFile::fake()->image('photo2.jpg')
]);
// Assert one or more files were stored...
Storage::disk('photos')->assertExists('photo1.jpg');
Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);
// Assert one or more files were not stored...
Storage::disk('photos')->assertMissing('missing.jpg');
Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);
// Assert that the number of files in a given directory matches the expected count...
Storage::disk('photos')->assertCount('/wallpapers', 2);
// Assert that a given directory is empty...
Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
}
}默认情况下，fake 方法会删除其临时目录中的所有文件。若希望保留这些文件，可改用「persistentFake」方法。关于测试文件上传的更多信息，可参阅 HTTP 测试文档中关于文件上传的说明。
WARNING
image 方法需要 GD 扩展。
自定义文件系统
Laravel 的 Flysystem 集成开箱即用支持若干「驱动」；不过 Flysystem 并不局限于此，还为许多其他存储系统提供了适配器。若要在 Laravel 应用中使用这些额外适配器，可以创建自定义驱动。
要定义自定义文件系统，你需要一个 Flysystem 适配器。下面我们向项目添加一个由社区维护的 Dropbox 适配器：
composer require spatie/flysystem-dropbox接下来，你可以在应用某个服务提供者的 boot 方法中注册该驱动。为此，应使用 Storage facade 的 extend 方法：
<?php
namespace App\Providers;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Filesystem\FilesystemAdapter;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Filesystem;
use Spatie\Dropbox\Client as DropboxClient;
use Spatie\FlysystemDropbox\DropboxAdapter;
class AppServiceProvider extends ServiceProvider
{
/**
* Register any application services.
*/
public function register(): void
{
// ...
}
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Storage::extend('dropbox', function (Application $app, array $config) {
$adapter = new DropboxAdapter(new DropboxClient(
$config['authorization_token']
));
return new FilesystemAdapter(
new Filesystem($adapter, $config),
$adapter,
$config
);
});
}
}extend 方法的第一个参数是驱动名称，第二个参数是接收 $app 与 $config 变量的闭包。该闭包必须返回 Illuminate\Filesystem\FilesystemAdapter 实例。$config 变量包含 config/filesystems.php 中为指定磁盘定义的值。
创建并注册扩展的服务提供者后，即可在 config/filesystems.php 配置文件中使用 dropbox 驱动。