管理静态文件（例如 图像、JavaScript、CSS) — Django 文档

管理静态文件（例如 图片、JavaScript、CSS）

网站通常需要提供其他文件，例如图像、JavaScript 或 CSS。 在 Django 中，我们将这些文件称为“静态文件”。 Django 提供了 django.contrib.staticfiles 来帮助你管理它们。

此页面描述了如何提供这些静态文件。

配置静态文件

1. 确保 django.contrib.staticfiles 包含在您的 :setting:`INSTALLED_APPS` 中。

2. 在您的设置文件中，定义 :setting:`STATIC_URL`，例如：

   STATIC_URL = '/static/'

3. 在您的模板中，使用 :ttag:`static` 模板标记使用配置的 :setting:`STATICFILES_STORAGE` 为给定的相对路径构建 URL。

   {% load static %}
   <img src="{% static 'my_app/example.jpg' %}" alt="My image">

4. 将静态文件存储在应用中名为 static 的文件夹中。 例如my_app/static/my_app/example.jpg。

提供文件

除了这些配置步骤之外，您还需要实际提供静态文件。

在开发过程中，如果使用 django.contrib.staticfiles，当 :setting:`DEBUG` 为 :djadmin:`runserver` 时，会自动完成设置为 True（见 django.contrib.staticfiles.views.serve()）。

这种方法效率低下，可能不安全，因此不适合生产。

有关在生产环境中提供静态文件的正确策略，请参阅 部署静态文件 。

您的项目可能还有与特定应用程序无关的静态资产。 除了在应用程序中使用 static/ 目录之外，您还可以在设置文件中定义目录列表 (:setting:`STATICFILES_DIRS`)，Django 还将在其中查找静态文件。 例如：

STATICFILES_DIRS = [
    BASE_DIR / "static",
    '/var/www/static/',
]

有关 staticfiles 如何查找文件的详细信息，请参阅 :setting:`STATICFILES_FINDERS` 设置的文档。

静态文件命名空间

现在我们 可能 能够将我们的静态文件直接放在 my_app/static/ 中（而不是创建另一个 my_app 子目录），但这实际上是一个坏主意。 Django 将使用它找到的第一个名称匹配的静态文件，如果您在 different 应用程序中有一个同名的静态文件，Django 将无法区分它们。 我们需要能够将 Django 指向正确的位置，而确保这一点的最佳方法是通过 命名空间 它们。 也就是说，将这些静态文件放在以应用程序本身命名的 另一个 目录中。

您可以通过指定 前缀 来命名 :setting:`STATICFILES_DIRS` 中的静态资产。

在开发期间提供静态文件

如果您使用 django.contrib.staticfiles 如上所述，:djadmin:`runserver` 将在 :setting:`DEBUG` 设置为时自动执行此操作True。 如果 :setting:`INSTALLED_APPS` 中没有 django.contrib.staticfiles，您仍然可以使用 django.views.static.serve() 手动提供静态文件看法。

这不适合生产使用！ 一些常见的部署策略，参见部署静态文件。

例如，如果您的 :setting:`STATIC_URL` 定义为 /static/，您可以通过将以下代码段添加到您的 urls.py 来实现：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

笔记

此辅助函数仅在调试模式下工作，并且仅当给定的前缀是本地的（例如 /static/) 而不是 URL（例如 http://static.example.com/）。

另外这个辅助函数只服务于实际的 :setting:`STATIC_ROOT` 文件夹； 它不会像 django.contrib.staticfiles 那样执行静态文件发现。

在开发过程中提供用户上传的文件

在开发过程中，您可以使用 django.views.static.serve() 视图从 :setting:`MEDIA_ROOT` 提供用户上传的媒体文件。

这不适合生产使用！ 一些常见的部署策略，参见部署静态文件。

例如，如果您的 :setting:`MEDIA_URL` 定义为 /media/，您可以通过将以下代码段添加到您的 urls.py 来实现：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

笔记

此辅助函数仅在调试模式下工作，并且仅当给定的前缀是本地的（例如 /media/) 而不是 URL（例如 http://media.example.com/）。

测试

当运行使用实际 HTTP 请求而不是内置测试客户端的测试时（即 当使用内置的 LiveServerTestCase) 时，静态资产需要与其余内容一起提供，以便测试环境尽可能忠实地再现真实的内容，但 LiveServerTestCase 只有非常基本静态文件服务功能：它不知道 staticfiles 应用程序的查找器功能，并假设静态内容已在 :setting:`STATIC_ROOT` 下收集。

正因为如此，staticfiles 发布了自己的 django.contrib.staticfiles.testing.StaticLiveServerTestCase，这是一个内置的子类，能够在执行过程中透明地为所有资产提供服务。这些测试的方式与我们在开发时使用 DEBUG = True 得到的非常相似，即 无需先使用 :djadmin:`collectstatic` 收集它们。

部署

django.contrib.staticfiles 提供了一个方便的管理命令，用于将静态文件收集在一个目录中，以便您可以轻松地为它们提供服务。

1. 将 :setting:`STATIC_ROOT` 设置设置为您希望提供这些文件的目录，例如：

   STATIC_ROOT = "/var/www/example.com/static/"

2. 运行 :djadmin:`collectstatic` 管理命令：

   $ python manage.py collectstatic

   这会将静态文件夹中的所有文件复制到 :setting:`STATIC_ROOT` 目录中。

3. 使用您选择的 Web 服务器来提供文件。 部署静态文件涵盖了一些常见的静态文件部署策略。

了解更多

本文档涵盖了基础知识和一些常见的使用模式。 有关 django.contrib.staticfiles 中包含的所有设置、命令、模板标签和其他部分的完整详细信息，请参阅 静态文件参考 。