Django 1.8.2 文档

« previous | up | next »

管理静态文件（CSS、图片等）

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

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

配置静态文件

  1. 确认django.contrib.staticfiles 包含在你的INSTALLED_APPS 中。

  2. 在你的settings 文件中定义STATIC_URL，例如：

    STATIC_URL = '/static/'

  3. 在模板中，你可以硬编码/static/my_app/myexample.jpg 这样的URL，或者使用static 模板标签以及配置的STATICFILES_STORAGE为给出的相对路径创建URL（这使得换成CDN 来保存静态文件更加容易）。

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

  4. 在你的应用中，将静态文件存储在名为static 目录下。例如：my_app/static/my_app/myimage.jpg。

启用静态文件服务

除了这些配置步骤之外，实际中你还需要启用静态文件服务。

在开发过程中，如果你使用django.contrib.staticfiles，当DEBUG 设置成True 时，runserver 会自动启用静态文件服务（参见django.contrib.staticfiles.views.serve()）。

这个方法非常低效而且可能不安全，所以它不适合线上环境。

关于线上环境保存静态文件的策略，参见部署静态文件。

你的项目可能还有一些静态文件不属于任何一个特定的应用。除了在应用中使用static/ 目录，你还可以在settings 文件中定义一个目录列表（STATICFILES_DIRS），Django 会在其中查找静态文件。例如：

STATICFILES_DIRS = (
    os.path.join(BASE_DIR, "static"),
    '/var/www/static/',
)

staticfiles 如何查找静态文件的细节，请参见STATICFILES_FINDERS 设置的文档。

静态文件的命名空间

现在，我们虽然能够将静态文件直接放在my_app/static/之下（而不用创建另外一个my_app 子目录），但是这是一个坏主意。Django 将使用它找到的名称匹配第一个静态文件， 如果你在另外一个不同 的应用中有相同名称的静态文件，Django 将无法区分它们。我们需要让Django 能够找到正确的静态文件，最简单的方法是给它们加上命名空间。方法是将这些静态文件放在与应用同名的另外一个目录中。

开发过程中启用静态文件服务

如上所述，如果你启用django.contrib.staticfiles，当DEBUG 设置为True 时，runserver 将自动启用静态文件服务。如果django.contrib.staticfiles 不在INSTALLED_APPS 中，你仍然可以使用django.contrib.staticfiles.views.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.contrib.staticfiles.views.serve() 视图，处理用户上传的来自于MEDIA_ROOT的media文件。

注意：该方式不适合在线上环境中使用! 关于一些常见的部署策略，请参阅部署静态文件一节.

例如，如果将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)

注意：

该辅助函数仅在debug模式下工作，而且仅当给定的前缀是本地目录 (例如 /media/)而不能是一个URL (例如http://media.example.com/)..

测试

When running tests that use actual HTTP requests instead of the built-in testing client (i.e. when using the built-in LiveServerTestCase) the static assets need to be served along the rest of the content so the test environment reproduces the real one as faithfully as possible, but LiveServerTestCase has only very basic static file-serving functionality: It doesn’t know about the finders feature of the staticfiles application and assumes the static content has already been collected under STATIC_ROOT. 当使用真正的HTTP请求而不是内建测试用client的时候(例如使用内建的LiveServerTestCase)  静态内容需要和其他内容一起被提供,便于让测试环境尽可能的和生产环境相同,但是LiveServerTestCase 只用最基本的静态文件提供功能: I它不了解staticfiles 的特性并且认为所有静态内容都被收集在STATIC_ROOT下

因此，staticfiles发送自己的django.contrib.staticfiles.testing.StaticLiveServerTestCase，这是一个内置子类，具有透明地服务所有资产的能力在这些测试执行期间，以非常类似于在开发时使用DEBUG = True即，不必首先使用collectstatic来收集它们。

New in Django 1.7:

django.contrib.staticfiles.testing.StaticLiveServerTestCase是Django 1.7中的新功能。以前，它的功能由django.test.LiveServerTestCase提供。

部署

django.contrib.staticfiles 提供一个便捷的管理命令用于将静态文件收集到一个目录中,这样你就可以轻松地供给这些文件

  1. 将 STATIC_ROOT设置为你提供文件的目录,例子如下

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

  2. 运行collectstatic管理命令

    $ python manage.py collectstatic

    这会将所有你在所有static目录下的所有的文件都复制到 STATIC_ROOT 目录中

  3. 使用你所选择的Web服务器来提供这些文件Deploying static files 讲了一些常见的讲台文件部署策略

了解更多

此文档覆盖了基础,常见的使用范式.对于 django.contrib.staticfiles所包含的完整设置,命令,模板标签,以及其他内容, 见the staticfiles reference.

« previous | up | next »