静的ファイル (画像、JavaScript、CSS など) の管理

ウェブサイトではふつう、画像や JavaScript、CSS などの追加のファイルを配信する必要があります。Django では、こうしたファイルのことを「静的ファイル (static files)」と呼んでいます。静的ファイルの管理を簡単にするために、Django は django.contrib.staticfiles を提供しています。

このページでは、こうした静的ファイルの配信の仕方について説明します。

静的ファイルの設定

  1. django.contrib.staticfiles が設定ファイルの INSTALLED_APPS に含まれていることを確認してください。

  2. 設定ファイルの中で、STATIC_URL を設定します。たとえば、次のようになります。

    STATIC_URL = '/static/'

  3. テンプレート中で、静的ファイルへの URL を /static/my_app/myexample.jpg のようにハードコーディングするか、または、より望ましい方法として static テンプレートタグを記述して、設定した STATICFILES_STORAGE ストレージを使うことにより、指定した相対パスから URL を動的に構築します (この方法は特に、静的ファイルを配信する CDN を切り替えたくなった時に、作業を簡単にしてくれます)。

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

  4. アプリケーション内に static``というフォルダを作って静的ファイルを保存してください。例えば、``my_app/static/my_app/example.jpg となります。

ファイルを配信する

これらの設定の手順に加えて、実際に静的ファイルを配信する必要があります。

開発中に django.contrib.staticfiles を使用する場合には、DEBUG を True に設定して runserver を実行すれば、自動的に設定が行われます。(詳しくは、django.contrib.staticfiles.views.serve() を参照)

ただし、この方法は 極めて非効率 であり、セキュリティ上の問題がある 可能性が高いため、実際の製品では使うべきではありません。

製品環境中で静的ファイルを配信するための適切な戦略については、静的ファイルのデプロイ を読んでください。

プロジェクトには、特定のアプリケーションに紐付けられていない 静的な assets があることがあります。その場合には、アプリケーション内の static/ ディレクトリの他に、設定ファイルでディレクトリのリスト (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 は自動的にこの処理を行います。もし 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)

注釈

このヘルパー関数はデバッグモードでプレフィックスが URL (例えば http://static.example.com/) でなくローカルのパス (例えば /static/) である場合にのみ利用できます。

またこのヘルパー関数は STATIC_ROOT のフォルダのみを利用します; django.contrib.staticfiles のように静的ファイルの探索は行いません。

ユーザーによりアップロードされるファイルの開発時の取扱い

開発中は、ユーザーによってアップロードされたメディアファイルを django.views.static.serve() ビューを利用している MEDIA_ROOT から利用できます。

その機能はプロダクション環境で利用するのに適していません! 一般的なデプロイ方法に関しては 静的ファイルのデプロイ を参照ください。

例えば、 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)

注釈

このヘルパー関数はデバッグモードでプレフィックスが URL (例えば http://media.example.com/) ではなくローカルパス (例えば /media/) である場合にのみ利用できます。

テスト

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.

Because of this, staticfiles ships its own django.contrib.staticfiles.testing.StaticLiveServerTestCase, a subclass of the built-in one that has the ability to transparently serve all the assets during execution of these tests in a way very similar to what we get at development time with DEBUG = True, i.e. without having to collect them using collectstatic first.

デプロイ

django.contrib.staticfiles provides a convenience management command for gathering static files in a single directory so you can serve them easily.

  1. Set the STATIC_ROOT setting to the directory from which you’d like to serve these files, for example:

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

  2. Run the collectstatic management command:

    $ python manage.py collectstatic

    This will copy all files from your static folders into the STATIC_ROOT directory.

  3. Use a web server of your choice to serve the files. 静的ファイルのデプロイ covers some common deployment strategies for static files.

さらに学ぶ

This document has covered the basics and some common usage patterns. For complete details on all the settings, commands, template tags, and other pieces included in django.contrib.staticfiles, see the staticfiles reference.

Back to Top