---
title: "文件存储 API"
version: 3.2
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/3.2/ref/files/storage/
canonical: https://djangodocs.dev/zh-hans/3.2/ref/files/storage/
---
# 文件存储 API

## 获取当前存储类

Django 提供了两种方便的方式来访问当前的存储类。

#### `class DefaultStorage`

[`DefaultStorage`](#django.core.files.storage.DefaultStorage) 在内部使用 [`get_storage_class()`](#django.core.files.storage.get_storage_class)，提供对当前默认存储系统的惰性访问，该系统由 [`DEFAULT_FILE_STORAGE`](/zh-hans/3.2/ref/settings/#std-setting-DEFAULT_FILE_STORAGE) 定义。

#### `get_storage_class(import_path=None)`

返回一个实现存储 API 的类或模块。

当调用时没有提供 `import_path` 参数时，`get_storage_class` 将返回当前默认的存储系统，定义为 [`DEFAULT_FILE_STORAGE`](/zh-hans/3.2/ref/settings/#std-setting-DEFAULT_FILE_STORAGE)。如果提供了 `import_path`，`get_storage_class` 将尝试从给定的路径导入类或模块，如果成功则返回。如果导入不成功，将引发一个异常。

## `FileSystemStorage` 类

#### `class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)`

[`FileSystemStorage`](#django.core.files.storage.FileSystemStorage) 类实现了本地文件系统的基本文件存储。它继承自 [`Storage`](#django.core.files.storage.Storage) 类，并提供了其中所有公开方法的实现。

#### `location`

存放文件的目录的绝对路径。 默认为你的 [`MEDIA_ROOT`](/zh-hans/3.2/ref/settings/#std-setting-MEDIA_ROOT) 配置的值。

#### `base_url`

为存储在此位置的文件提供服务的 URL。默认为你的 [`MEDIA_URL`](/zh-hans/3.2/ref/settings/#std-setting-MEDIA_URL) 配置的值。

#### `file_permissions_mode`

保存文件时，文件系统将获得的权限。默认为 [`FILE_UPLOAD_PERMISSIONS`](/zh-hans/3.2/ref/settings/#std-setting-FILE_UPLOAD_PERMISSIONS)。

#### `directory_permissions_mode`

保存目录时，该目录将获得的文件系统权限，默认为 [`FILE_UPLOAD_DIRECTORY_PERMISSIONS`](/zh-hans/3.2/ref/settings/#std-setting-FILE_UPLOAD_DIRECTORY_PERMISSIONS)。

> **Note**
>
> 如果给定的文件名不存在，`FileSystemStorage.delete()` 方法不会引发异常。

#### `get_created_time(name)`

返回系统 ctime 的 [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)，即 [`os.path.getctime()`](https://docs.python.org/3/library/os.path.html#os.path.getctime)。在某些系统上（如 Unix），这是最后一次修改元数据的时间，而在其他系统上（如 Windows），这是文件的创建时间。

> **Changed in Django 3.1**
>
> 在 `FileSystemStorage.save()` 方法中增加了对 [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) 的支持。

## `Storage` 类

#### `class Storage`

[`Storage`](#django.core.files.storage.Storage) 类为存储文件提供了一个标准化的 API，以及一组默认行为，所有其他存储系统可以根据需要继承或覆盖。

> **Note**
>
> 当方法返回未处理的 `datetime` 对象时，所使用的有效时区将是 `os.environ['TZ']` 的当前值；注意，这通常是由 Django 的 [`TIME_ZONE`](/zh-hans/3.2/ref/settings/#std-setting-TIME_ZONE) 设置的。

#### `delete(name)`

删除 `name` 引用的文件。如果目标存储系统不支持删除，这将引发 `NotImplementedError`。

#### `exists(name)`

如果给定名称所引用的文件已经存在于存储系统中，则返回 `True`；如果该名称可用于新文件，则返回 `False`。

#### `get_accessed_time(name)`

返回文件最后访问时间的 [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)。对于不能返回最后访问时间的存储系统，将引发 [`NotImplementedError`](https://docs.python.org/3/library/exceptions.html#NotImplementedError)。

如果 [`USE_TZ`](/zh-hans/3.2/ref/settings/#std-setting-USE_TZ) 为 `True`，则返回一个处理过的 `datetime`，否则返回一个当地时区的未处理的 `datetime`。

#### `get_alternative_name(file_root, file_ext)`

根据 `file_root` 和 `file_ext` 参数返回一个替代的文件名，一个下划线加上一个随机的 7 个字符的字母数字字符串被附加到文件名的扩展名之前。

#### `get_available_name(name, max_length=None)`

返回一个基于 `name` 参数的文件名，该文件名在目标存储系统中是空闲的，可供新内容写入。

文件名的长度不会超过 `max_length`，如果提供的话。如果不能找到一个空闲的唯一文件名，将引发一个 [`SuspiciousFileOperation`](/zh-hans/3.2/ref/exceptions/#django.core.exceptions.SuspiciousOperation) 异常。

如果一个带有 `name` 的文件已经存在，则调用 [`get_alternative_name()`](/zh-hans/3.2/howto/custom-file-storage/#django.core.files.storage.get_alternative_name) 来获得一个替代名称。

#### `get_created_time(name)`

返回文件的创建时间的 [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)。对于不能返回创建时间的存储系统，将引发 [`NotImplementedError`](https://docs.python.org/3/library/exceptions.html#NotImplementedError)。

如果 [`USE_TZ`](/zh-hans/3.2/ref/settings/#std-setting-USE_TZ) 为 `True`，则返回一个处理过的 `datetime`，否则返回一个当地时区的未处理的 `datetime`。

#### `get_modified_time(name)`

返回文件最后修改时间的 [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)。对于不能返回最后修改时间的存储系统，将引发 [`NotImplementedError`](https://docs.python.org/3/library/exceptions.html#NotImplementedError)。

如果 [`USE_TZ`](/zh-hans/3.2/ref/settings/#std-setting-USE_TZ) 为 `True`，则返回一个处理过的 `datetime`，否则返回一个当地时区的未处理的 `datetime`。

#### `get_valid_name(name)`

根据 `name` 参数返回一个适合在目标存储系统中使用的文件名。

#### `generate_filename(filename)`

通过调用 [`get_valid_name()`](/zh-hans/3.2/howto/custom-file-storage/#django.core.files.storage.get_valid_name) 验证 `文件名`，并返回一个文件名传给 [`save()`](#django.core.files.storage.Storage.save) 方法。

`filename` 参数可能包含 [`FileField.upload_to`](/zh-hans/3.2/ref/models/fields/#django.db.models.FileField.upload_to) 返回的路径。在这种情况下，路径不会被传递给 [`get_valid_name()`](/zh-hans/3.2/howto/custom-file-storage/#django.core.files.storage.get_valid_name)，而是会被预输入到结果的名称中。

默认实现使用 [`os.path`](https://docs.python.org/3/library/os.path.html#module-os.path) 操作。如果不适合你的存储，请重写这个方法。

#### `listdir(path)`

列出指定路径的内容，返回一个二元元组列表，第一项是目录，第二项是文件。对于不能提供这种列表的存储系统，这将引发一个 `NotImplementedError`。

#### `open(name, mode='rb')`

打开由 `name` 给出的文件。请注意，虽然返回的文件保证是一个 `File` 对象，但实际上它可能是某个子类。在远程文件存储的情况下，这意味着读／写可能会很慢，所以要注意。

#### `path(name)`

本地文件系统路径，在这里可以使用 Python 的标准 `open()` 打开文件。对于不能从本地文件系统访问的存储系统，这将引发 `NotImplementedError`。

#### `save(name, content, max_length=None)`

使用存储系统保存一个新的文件，最好使用指定的名称。如果已经存在一个带有这个名字 `name` 的文件，存储系统可以根据需要修改文件名以获得一个唯一的名字。将返回存储文件的实际名称。

`max_length` 参数被传递给 [`get_available_name()`](/zh-hans/3.2/howto/custom-file-storage/#django.core.files.storage.get_available_name)。

`content` 参数必须是 [`django.core.files.File`](/zh-hans/3.2/ref/files/file/#django.core.files.File) 的实例，或者是一个可以用 `File` 包装的类文件对象。

#### `size(name)`

返回 `name` 引用的文件的总大小，以字节为单位。对于不能返回文件大小的存储系统，将引发 `NotImplementedError`。

#### `url(name)`

返回可以访问 `name` 引用的文件内容的URL。对于不支持通过 URL 访问的存储系统，这将引发 `NotImplementedError`。