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

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

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

静的ファイルの設定

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

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

    STATIC_URL = '/static/'

  3. テンプレート中では、static テンプレートタグを使うことで、設定済みの 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 を使用する場合には、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/) である場合にのみ利用できます。

テスト

ビルトインのテストクライアント (たとえば、ビルトインの LiveServerTestCase) ではなく実際の HTTP リクエストを使用してテストを実行している場合、テスト環境が現実の環境をできるだけ忠実に再現できるように、他のコンテンツと同じように静的アセットも配信する必要があります。しかし、LiveServerTestCase はとても基本的な静的ファイル配信機能しかないため、staticfiles アプリケーションの探索機能はなく、すでに静的コンテンツは 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 には、静的ファイルを単一のディレクトリに集約するための便利な管理コマンドがあるので、静的ファイルを簡単に配信することができます。

  1. STATIC_ROOT 設定で、どのディレクトリから静的ファイルを配信するかを指定します。たとえば:

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

  2. collectstatic 管理コマンドを実行します:

    $ python manage.py collectstatic

    これにより、各 static フォルダから STATIC_ROOT のディレクトリにファイルがコピーされます。

  3. あなた自身の選択で、ファイルを配信するウェブサーバーを使用してください。静的ファイルのデプロイ で、静的ファイルに対する一般的なデプロイの戦略を紹介しています。

さらに学ぶ

このドキュメントでは、基本および一般的な利用パターンを紹介しました。django.contrib.staticfiles に含まれるすべての設定、コマンド、テンプレートタグ、およびその他の事項に関する網羅的な詳細は、the staticfiles reference を参照してください。

Back to Top