理解 django.contrib.staticfiles

written on Thursday, July 26, 2012

Django 1.3 包含了一个新的 APP django.contrib.staticfiles 来帮助开发者管理渲染页面所需的 JS、CSS 等静态文件。

在 1.3 之前，所有的静态文件都是用 MEDIA_URL 和 MEDIA_ROOT 来控制的。为了和用户上传的文件作区分，staticfiles 的使我们可以将静态文件分配到 APP 目录或任意你指定的目录，分发 APP 时就更为方便了。

django.contrib.staticfiles 文档

MEDIA_XXX 和 STATIC_XXX 配置项的区别

MEDIA_XXX 配置项用来管理用户上传的文件。通常经由 FileFields 字段上传，它们保存在 settings.MEDIA_ROOT 指定的目录下，通过 settings.MEDIA_URL 指定的路径访问；
STATIC_XXX 配置项用来管理静态资源文件。CSS / JS 文件、png/jpg 图片等 app 提供的静态资源。它们通过 manage.py collectstatic 命令汇集到 settings.STATIC_ROOT 目录，并通过 settings.STATIC_URL 指定的路径访问。

使用 staticfiles

在 Django 1.3 中，staticfiles 默认是启用的。如果是从 1.3 之前的代码迁移过来，启用代码如下：

INSTALLED_APPS += ('django.contrib.staticfiles',)

TEMPLATE_CONTEXT_PROCESSORS += ('django.core.context_processors.static',)

STATIC_ROOT 配置项

STATIC_ROOT 被用来指定执行 manage.py collectstatic 时静态文件存放的路径。在生产环境下，集中存放静态资源有用利于使用 Lighttpd / Nginx 托管静态资源。为了方便调试，通常设置如下：

SITE_ROOT = os.path.dirname(os.path.abspath(__file__))
SITE_ROOT = os.path.abspath(os.path.join(SITE_ROOT, '../'))

STATIC_ROOT = os.path.join(SITE_ROOT, 'collectedstatic')

STATIC_URL 配置项

在 Django 模板中，我们可以引用 {{ STATIC_URL }} 变量避免把路径写死。通常设置如下：

STATIC_URL = '/static/'

ADMIN_MEDIA_PREFIX 配置项

ADMIN_MEDIA_PREFIX 必须为如下设置，以便 staticfiles 能够正确的找到 django.contrib.admin 的静态资源：

ADMIN_MEDIA_PREFIX = STATIC_URL + 'admin/'

在模板中使用 STATIC_URL

<link rel="stylesheet" href="{{ STATIC_URL }}css/core.css">

开发环境访问静态资源

设置 urls.py

from django.contrib.staticfiles.urls import staticfiles_urlpatterns
urlpatterns += staticfiles_urlpatterns()

注意：无须对上面的代码使用 if settings.DEBUG: 判断，staticfiles_urlpatterns() 函数会自己处理。

静态资源的存放和查找

开发环境下 staticfiles 查找静态资源的顺序取决于 STATICFILES_FINDERS 配置项，STATICFILES_FINDERS 缺省设置如下：

("django.contrib.staticfiles.finders.FileSystemFinder",
 "django.contrib.staticfiles.finders.AppDirectoriesFinder")

django.contrib.staticfiles.finders.FileSystemFinder 用来从 STATICFILES_DIRS 指定的路径中查找额外的静态文件；
django.contrib.staticfiles.finders.AppDirectoriesFinder 是从 INSTALLED_APPS 列表内的 APP 所在包的 static 目录中查找资源文件。

发布环境访问静态资源

首先应该执行 manage.py collectstatic 命令把所有 APP （包括 django.contrib.admin）的静态资源收集到 STATIC_ROOT 指定的目录
接着，我们需要配置 lighttpd/nginx 服务器，将 /static/ 路径指向 STATIC_ROOT 目录，提供静态资源的服务。详细细节请参考：Serving static files in production

扩展资料

真实世界的 Django 项目中，静态资源的管理要更复杂一些，要额外处理的事情包括：

Less / CoffeeScript 等自动编译成 CSS／JS
“压缩” CSS／JS 文件，以提高浏览器加载速度
合并零碎的 CSS／JS 文件，减少浏览器请求，降低服务器请求建立的频率
静态资源文件的版本化：浏览器会缓存静态文件，后台代码和静态资源都发生更新后，浏览器很可能从缓存提取过期的静态，导致页面显示异常

Django 静态资源管理利器 - django-pipeline 正是用来解决上述问题。正式的 Django 项目须注意并解决这些问题，尤其是处理静态资源的版本化。

This entry was tagged django and staticfiles

理解 django.contrib.staticfiles | Life @ Refactoring