管理静态文件(比如图片、JavaScript、CSS)¶
网站通常需要提供类似图片,JavaScript 或 CSS 的额外文件服务。在 Django 中,我们将这些文件称为“静态文件”。Django 提供了 django.contrib.staticfiles
帮你管理它们。
本页介绍如何为这些静态文件提供服务。
配置静态文件¶
确保
INSTALLED_APPS
包含了django.contrib.staticfiles
。在配置文件中,定义
STATIC_URL
,例子:STATIC_URL = '/static/'
在模板中,用
static
模板标签基于配置STATICFILES_STORAGE
位给定的相对路径构建 URL。{% load static %} <img src="{% static 'my_app/example.jpg' %}" alt="My image">
将你的静态文件保存至程序中名为
static
的目录中。例如my_app/static/my_app/example.jpg
。
为这些文件提供服务
除了这些配置步骤外,你还需要实际地为这些文件提供服务。
开发时,使用 django.contrib.staticfiles
,这一般会在 DEBUG
is set to True
情况下由 runserver
自动完成(参考 django.contrib.staticfiles.views.serve()
)。
该方法 极度低效 且 不怎么安全,所以这 不适合生产环境。
参考 部署静态文件 了解如何正确地在生产环境提供静态文件服务的策略。
你的工程可能包含未与任何应用绑定的静态资源。除了在 apps 中使用 static/
目录,你可以在配置文件中定义一个目录列表 (STATICFILES_DIRS
) ,Django 会从中寻找静态文件。例子:
STATICFILES_DIRS = [
BASE_DIR / "static",
'/var/www/static/',
]
参考 STATICFILES_FINDERS
配置的文档了解 staticfiles
是如何找到你的文件的细节。
静态文件命名空间
现在,我们 也许 能直接将静态文件放入 my_app/static/
目录(而不是创建另一个 my_app
子目录),不过这实际上是个坏主意。Django 会使用第一个名字匹配的静态文件,若你在 不同的 应用程序中有一个同名静态文件,Django 无力区分它们。我们需要为 Django 指出正确的那个,而最好的方式就是使用 命名空间。也就是说,将这些静态文件放在 另一个 以应用程序名本身命名的目录下。
你可以通过指定 prefixes 在 STATICFILES_DIRS
中为静态资源做命名。
开发时提供静态文件服务¶
若你使用了前文所述的 django.contrib.staticfiles
, runserver
会在 DEBUG
为 True
时自动处理。若你未在 INSTALLED_APPS
中包含 django.contrib.staticfiles
,你仍能手动通过 django.views.static.serve()
为静态文件提供服务。
这不适合生产环境!常见的部署策略请参考 部署静态文件。
例如,若 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)
注解
该助手函数只能在 debug 模式下生效,且要求前缀是本地的(例如 /static/
),不是一个 URL (例如 http://static.example.com/
)。
当然,助手函数只为实际的 STATIC_ROOT
目录提供服务;它不会像 django.contrib.staticfiles
一样搜索静态文件。
开发期间保存用户上传的文件¶
开发期间,你能用 django.views.static.serve()
视图为用户上传的媒体文件提供服务。
这不适合生产环境!常见的部署策略请参考 部署静态文件。
例如,如果您的配置 MEDIA_URL
定义为 /media/
,您可以通过将以下代码段添加到您的配置 ROOT_URLCONF
:: 。
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)
注解
该助手函数只能在 debug 模式下生效,且要求前缀是本地的(例如 /static/
),不是一个 URL (例如 http://media.example.com/
)。
测试¶
运行使用真实 HTTP 请求(而不是内置的测试客户端,即内置的 LiveServerTestCase
)的测试用例时,静态资源要与剩余内容分别提供服务,这样,测试环境才能尽量重现真实的问题。但 LiveServerTestCase
只拥有非常基本的为静态文件提供服务的能力:它并不知道 staticfiles
应用的查找功能,且总是假设静态内容已被收集至 STATIC_ROOT
目录下。
因此, staticfiles
自带了 django.contrib.staticfiles.testing.StaticLiveServerTestCase
,这是一个内置子类,能够透明地以类似我们在开发阶段 DEBUG = True
时获得的方式为所有静态资源在测试期间提供服务。即无需先用 collectstatic
收集它们。
部署¶
django.contrib.staticfiles
提供了一个便利的管理命令,用于将静态文件收集至独立目录,方便你为它们提供服务。
将
STATIC_ROOT
配置成你喜欢的目录,在这个目录提供服务,例如:STATIC_ROOT = "/var/www/example.com/static/"
运行
collectstatic
管理命令:$ python manage.py collectstatic
这将会把静态目录下的所有文件拷贝至
STATIC_ROOT
目录。选一个 Web 服务器为这些文件提供服务。 文档 部署静态文件 介绍了静态文件的常见部署策略。
了解更多¶
本文档已覆盖基础和常见模式。对于所有配置项,命令,模板标签和其他包含在 django.contrib.staticfiles
碎片的全部细节,参考 静态文件参考。