staticfiles アプリ

django.contrib.staticfiles は、各アプリケーション（と、あらかじめ指定した他の場所）から静的ファイルを収集し、本番環境で簡単に提供できるように一か所にまとめます。

参考

静的ファイルアプリの導入と活用例については、 静的ファイル (画像、JavaScript、CSS など) を管理する を参照してください。静的ファイルのデプロイに関するガイドラインについては、 静的ファイルをデプロイする を参照してください。

設定

次の設定に関する詳細については、 静的ファイルの設定 を参照してください。

• STORAGES
• STATIC_ROOT
• STATIC_URL
• STATICFILES_DIRS
• STATICFILES_STORAGE
• STATICFILES_FINDERS

管理コマンド

django.contrib.staticfiles は3つの管理コマンドを提供します。

collectstatic

django-admin collectstatic

静的ファイルを STATIC_ROOT に収集します。

デフォルトでは、重複するファイル名はテンプレートの解決方法と同様に処理されます。すなわち、指定された場所のいずれかで最初に見つかったファイルが使用されます。どのファイルが反映されたかわからない場合は、 findstatic コマンドを使用して、どのファイルが適用されたかを確認できます。

その後、再度 collectstatic を実行すると、（ STATIC_ROOT が空でない限り）収集元のファイルは、そのタイムスタンプが STATIC_ROOT にあるファイルのタイムスタンプよりも後の日時であるときのみコピーされます。そのため、 INSTALLED_APPS からアプリケーションを削除するときは、 collectstatic --clear を実行することで古い静的ファイルを削除すると良いでしょう。

ファイルの検索には、 有効化された検索システム が使用されます。デフォルトでは、 STATICFILES_DIRS で定義されたすべての場所と、 INSTALLED_APPS 設定で指定されたアプリケーションの 'static' ディレクトリを参照します。

collectstatic コマンドは、実行するたび STORAGES から staticfiles ストレージバックエンドの post_process() メソッドを呼び出し、この管理コマンドによって見つかったファイルパスのリストを返します。同時に、 collectstatic のすべてのコマンドラインオプションを受け取ります。このオプションは、デフォルトでは ManifestStaticFilesStorage に渡されます。

デフォルトでは、収集されたファイルは FILE_UPLOAD_PERMISSIONS から、収集されたディレクトリは FILE_UPLOAD_DIRECTORY_PERMISSIONS からアクセス許可を受け取ります。これらのファイルまたはディレクトリに異なるアクセス許可を設定したい場合は、静的ファイルストレージのクラス のいずれかをサブクラス化し、それぞれ file_permissions_mode および/または directory_permissions_mode パラメータを指定します。以下に例を示します。

from django.contrib.staticfiles import storage


class MyStaticFilesStorage(storage.StaticFilesStorage):
    def __init__(self, *args, **kwargs):
        kwargs["file_permissions_mode"] = 0o640
        kwargs["directory_permissions_mode"] = 0o760
        super().__init__(*args, **kwargs)

次に、 STORAGES 設定で staticfiles ストレージバックエンドを 'path.to.MyStaticFilesStorage' と指定してください。

この管理コマンドでよく使われるオプションをいくつか示します。

--noinput, --no-input

ユーザーにいかなる入力も要求せずに処理を実行します。

--ignore PATTERN, -i PATTERN

指定した glob スタイルのパターンに一致するファイル、ディレクトリ、またはパスからの収集を行わないようにします。対象外のパターンが複数ある場合は、その数だけ指定してください。また、パスを指定するとき、Windowsでも常にスラッシュを使用してください。

--dry-run, -n

ファイルシステムを変更すること以外の全てを行います。

--clear, -c

既存のファイルを削除してから、元のファイルをコピーまたはリンクします。

--link, -l

各ファイルをコピーする代わりに、シンボリックリンクを作成します。

--no-post-process

STORAGES に設定された staticfiles ストレージバックエンドの post_process() メソッドを呼び出さないようにします。

--no-default-ignore

一般的なプライベート glob スタイルのパターンである 'CVS' 、 '.*' および '*~' を収集対象外としないようにします。

すべてのオプションのリストは、次のコマンドを実行してコマンドのヘルプから参照してください。

Linux/macOS

$ python manage.py collectstatic --help

Windows

...\> py manage.py collectstatic --help

無視パターンリストをカスタマイズする

デフォルトの無視パターンリストは ['CVS', '.*', '*~'] ですが、これは collectstatic の呼び出しのたびに --ignore オプションを指定することなく、より永続的な方法でカスタマイズできます。以下のように、 ignore_patterns 属性をオーバーライドしたカスタムの AppConfig クラスを実装し、 INSTALLED_APPS 設定で 'django.contrib.staticfiles' をそのカスタムクラスのパスに置き換えてください。

from django.contrib.staticfiles.apps import StaticFilesConfig


class MyStaticFilesConfig(StaticFilesConfig):
    ignore_patterns = [...]  # your custom ignore list

findstatic

django-admin findstatic staticfile [staticfile ...]

有効な検索機能を使用して、1つ以上の相対パスを検索します。

例:

Linux/macOS

$ python manage.py findstatic css/base.css admin/js/core.js
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Found 'admin/js/core.js' here:
  /home/polls.com/src/django/contrib/admin/media/js/core.js

Windows

...\> py manage.py findstatic css\base.css admin\js\core.js
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Found 'admin/js/core.js' here:
  /home/polls.com/src/django/contrib/admin/media/js/core.js

findstatic --first

デフォルトでは、一致するすべてのファイルのパスが表示されます。最初に見つかったファイルの相対パスだけを返すには、 --first オプションを使用してください。

Linux/macOS

$ python manage.py findstatic css/base.css --first
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css

Windows

...\> py manage.py findstatic css\base.css --first
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css

指定したパスに対して収集された静的ファイルが正確に表示されるので、デバッグの助けになります。

--verbosity フラグを 0 に設定することで、追加の出力を抑制し、パス名のみを取得できます。

Linux/macOS

$ python manage.py findstatic css/base.css --verbosity 0
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css

Windows

...\> py manage.py findstatic css\base.css --verbosity 0
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css

一方、 --verbosity フラグを2に設定することで、検索されたすべてのディレクトリを取得することもできます。

Linux/macOS

$ python manage.py findstatic css/base.css --verbosity 2
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Looking in the following locations:
  /home/special.polls.com/core/static
  /home/polls.com/core/static
  /some/other/path/static

Windows

...\> py manage.py findstatic css\base.css --verbosity 2
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Looking in the following locations:
  /home/special.polls.com/core/static
  /home/polls.com/core/static
  /some/other/path/static

runserver

django-admin runserver [addrport]

staticfiles アプリケーションが インストール されている場合、 runserver コマンドを上書きし、静的ファイルの自動サービスを追加します。ファイルのサービスは MIDDLEWARE を経由しません。

このコマンドには、以下のオプションが追加されています。

--nostatic

--nostatic オプションを使用すると、 staticfiles アプリケーションによる静的ファイルの配信を完全に無効にします。このオプションは、 INSTALLED_APPS 設定に staticfiles アプリケーションが含まれている場合にのみ利用可能です。

使用例:

Linux/macOS

$ django-admin runserver --nostatic

Windows

...\> django-admin runserver --nostatic

--insecure

--insecure オプションを使用すると、 DEBUG 設定が False の場合でも、静的ファイルを強制的に staticfiles アプリで配信します。これを使用する場合、 非常に非効率的 で、おそらく 安全ではない ことを受け入れる必要があります。これはローカル開発のみを目的としているので、 本番環境では使用しないでください 。また、 staticfiles アプリがプロジェクトの INSTALLED_APPS 設定に含まれている場合のみ利用可能です。

--insecure オプションは ManifestStaticFilesStorage と同時に使用することはできません。

使用例:

Linux/macOS

$ django-admin runserver --insecure

Windows

...\> django-admin runserver --insecure

ストレージ

StaticFilesStorage

class storage.StaticFilesStorage

FileSystemStorage ストレージバックエンドのサブクラスです。 STATIC_ROOT 設定を基本ファイルシステムの場所として、STATIC_URL 設定を基本URLとして使用します。

storage.StaticFilesStorage.post_process(paths, **options)

このメソッドがストレージ上で定義されている場合は、 collectstatic 管理コマンドが実行されるたびに呼び出され、見つかったファイルのローカルストレージとパス、およびコマンドラインオプションが辞書として渡されます。この処理は original_path 、 processed_path 、 processed の3つの値のタプルを生成します。パスの値は文字列であり、 processed は値が事後処理されたかどうかを示すブール値であり、事後処理が失敗した場合は例外が格納されます。

ManifestStaticFilesStorage は、これを裏で使用してパスをハッシュ化された対応するパスに置き換え、キャッシュを適切に更新します。

ManifestStaticFilesStorage

class storage.ManifestStaticFilesStorage

StaticFilesStorage のストレージバックエンドのサブクラスです。ファイル名を処理する際に、ファイルの内容のMD5ハッシュをファイル名に追加して保存します。たとえば、ファイル css/styles.css は css/styles.55e7cbb9ba48.css として保存されます。

このストレージの目的は、古いファイルを提供し続けることです。なぜなら、古いファイルはあなたや第三者のプロキシサーバによってキャッシュされており、いくつかのページがまだそれらのファイルを参照することがあるからです。また、展開されたファイルに far future Expires headers を適用して、次回のページ訪問の読み込み時間を高速化する場合にも非常に役立ちます。

保存されたファイル内のパスが他の保存されたファイルと一致する場合、ストレージバックエンドは自動的にキャッシュされたコピーのパスでそれらのパスを置き換えます（このとき、 post_process() メソッドを使用）。これらのパスを検索するために使用される正規表現（ django.contrib.staticfiles.storage.HashedFilesMixin.patterns ）は以下に対応しています。

• @import ルールと url() ステートメントの Cascading Style Sheets
• CSS および JavaScript ファイル内の Source map コメント

ManifestStaticFilesStorage のサブクラスを作成し、 support_js_module_import_aggregation 属性を True に設定すると、実験的な正規表現を使用して以下にも対応できます。

• JavaScript の modules import
• JavaScriptの modules aggregation

たとえば、以下のような 'css/styles.css' を定義します。

@import url("../admin/css/base.css");

...これは ManifestStaticFilesStorage ストレージバックエンドの url() メソッドを呼び出すことで置換され、最終的に 'css/styles.55e7cbb9ba48.css' というファイルが以下の内容で保存されます。

@import url("../admin/css/base.27e20196a850.css");

ローカルファイルに対する integrity HTML属性の使用方法

<script> や <link> のようなタグ内で任意の integrity 属性を使用する場合、その値はファイルシステムに保存されている状態ではなく、提供されるファイルに基づいて計算されるべきです。これは、静的ファイルがどのように収集されるかによって、そのチェックサムが変更され得るため、特に重要です（例えば、collectstatic を使用した場合）。現時点では、このための既製のツールは用意されていません。

マニフェストファイルの場所は、manifest_storage 引数を設定するカスタムの ManifestStaticFilesStorage サブクラスを使用することで変更できます。たとえば:

from django.conf import settings
from django.contrib.staticfiles.storage import (
    ManifestStaticFilesStorage,
    StaticFilesStorage,
)


class MyManifestStaticFilesStorage(ManifestStaticFilesStorage):
    def __init__(self, *args, **kwargs):
        manifest_storage = StaticFilesStorage(location=settings.BASE_DIR)
        super().__init__(*args, manifest_storage=manifest_storage, **kwargs)

コメント内の参照

ManifestStaticFilesStorage は、コメントアウトされた文内のパスを無視しません。これにより、存在しないパスで クラッシュする可能性があります 。コメントをチェックし、必要に応じて削除するべきです。

Changed in Django 4.2:

import と export ステートメント内でJavaScriptモジュールへのパスを見つけるための実験的なオプションサポートが追加されました。

storage.ManifestStaticFilesStorage.manifest_hash

New in Django 4.2.

この属性は、マニフェスト内のファイルが変更されるたびに変わる単一のハッシュを提供します。これは、サーバー上のアセットが変更されたこと（新しいデプロイメントが原因）をSPAに通知するのに役立つことがあります。

storage.ManifestStaticFilesStorage.max_post_process_passes

静的ファイルは他の静的ファイルを参照することがあるため、パスを置き換える処理を複数回行う必要があります。ファイルのハッシュが収束するまでこの処理を繰り返します。無限ループを防ぐため('foo.css' が 'bar.css' を参照し、その 'bar.css' が再び 'foo.css' を参照する例のように、ハッシュが収束しない場合)、ポストプロセッシングを中止する前に最大で何回のパスが可能かを設定しています。多くの参照があるケースでは、より多くのパスが必要になることがあります。最大パス数を増やすには、ManifestStaticFilesStorage をサブクラス化し、max_post_process_passes 属性を設定します。デフォルトは5です。

ManifestStaticFilesStorage を有効にするには、以下の要件を満たしていることを確認してください:

• STORAGES 設定の staticfiles ストレージバックエンドが 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage' に設定されていること
• DEBUG 設定が False に設定されていること
• collectstatic 管理コマンドを使用して、全ての静的ファイルを収集したこと

MD5ハッシュを作成することは、実行時にウェブサイトにとってパフォーマンス上の負担となる可能性があるため、 staticfiles は自動的に staticfiles.json というファイルに、処理されたすべてのファイルのハッシュ名とマッピングを保存します。これは collectstatic 管理コマンドを実行したときに一度だけ起こります。

storage.ManifestStaticFilesStorage.manifest_strict

実行時に staticfiles.json マニフェストでファイルが見つからない場合、ValueError が発生します。この動作は、ManifestStaticFilesStorage をサブクラス化し、manifest_strict 属性を False に設定することで無効にできます(存在しないパスはそのままになります)。

collectstatic を実行する必要があるため、このストレージは通常、テストの実行時には使用しないでください。テスト中は、 STORAGES 設定にある staticfiles ストレージバックエンドが 'django.contrib.staticfiles.storage.StaticFilesStorage' (デフォルト) のように他のものに設定されていることを確認してください。

storage.ManifestStaticFilesStorage.file_hash(name, content=None)

ファイルのハッシュ化された名前を作成する際に使用されるメソッドです。与えられたファイル名と内容に対するハッシュを返す必要があります。デフォルトでは、上述のように、内容のチャンクからMD5ハッシュを計算します。このメソッドをオーバーライドして、独自のハッシュアルゴリズムを使用することもできます。

ManifestFilesMixin

class storage.ManifestFilesMixin

カスタムストレージでこのミックスインを使用すると、 ManifestStaticFilesStorage が行うように、ファイルの内容の MD5 ハッシュをファイル名に追加します。

ファインダー・モジュール

staticfiles ファインダーには、ファインダーが検索したディレクトリパスのリストである searched_locations 属性があります。使用例:

from django.contrib.staticfiles import finders

result = finders.find("css/base.css")
searched_locations = finders.searched_locations

その他のヘルパー

staticfiles アプリ以外にも、静的ファイルを扱うためのいくつかの他のヘルパーがあります。

• django.template.context_processors.static() コンテキストプロセッサは、 RequestContext コンテキストでレンダリングされたすべてのテンプレートコンテキストに STATIC_URL を追加します。
• 組み込みのテンプレートタグ static はパスを受け取り、静的なプレフィックス STATIC_URL と urljoin します。もし django.contrib.staticfiles がインストールされていれば、代わりに STORAGES にある staticfiles ストレージバックエンドの url() メソッドを使用します。
• 組み込みのテンプレートタグ get_static_prefix は、テンプレート変数に静的プレフィックス STATIC_URL を代入し、変数として、または直接使用します。
• 同様のテンプレートタグ get_media_prefix は get_static_prefix のように動作しますが、 MEDIA_URL を使用します。
• staticfiles キーは django.core.files.storage.storages に含まれており、 staticfiles ストレージバックエンドの使用準備が整ったインスタンスが格納されています。

静的ファイル開発ビュー

静的ファイルツールは、主に静的ファイルを本番環境にうまくデプロイするために設計されています。これは通常、開発時には扱いが大変な専用の静的ファイルサーバーを意味します。そのため、staticfiles アプリには、開発中にローカルでファイルを提供するために使用できる 素早くて簡易なヘルパービュー が同梱されています。

views.serve(request, path)

このビュー関数は、開発中に静的ファイルを配信します。

警告

このビューは DEBUG が True の場合にのみ機能します。

このビューは 極めて非効率的 であり、おそらく セキュリティ上の問題 も抱えています。このビューは、 ローカル開発向け であり、 本番環境で使用するべきではありません 。

注釈

提供するファイルのコンテンツタイプを推測するために、このビューはPython標準ライブラリの mimetypes モジュールに依存しています。これは、その下層にあるプラットフォームのマップファイルにも依存しています。もし、このビューが特定のファイルに対して適切なコンテンツタイプを返さない場合、最も可能性が高いのは、プラットフォームのマップファイルが不正確であるか、更新が必要であることを意味しています。例えば、Red Hatディストリビューションで mailcap パッケージをインストールまたは更新すること、Debianディストリビューションで mime-support をインストールまたは更新すること、あるいはWindowsレジストリの HKEY_CLASSES_ROOT 下のキーを編集することによって、これを修正できます。

このビューは、 runserver (および DEBUG 設定が True に設定されている場合) によって自動的に有効になります。異なるローカル開発サーバーでこのビューを使用するには、主要なURL設定の末尾に以下のコードを追加してください:

from django.conf import settings
from django.contrib.staticfiles import views
from django.urls import re_path

if settings.DEBUG:
    urlpatterns += [
        re_path(r"^static/(?P<path>.*)$", views.serve),
    ]

注意: パターンの先頭 (r'^static/') はあなたの設定 (STATIC_URL) であるべきです。

これは少し厄介なので、これを代行してくれるヘルパー関数もあります:

urls.staticfiles_urlpatterns()

これは、すでに定義されているパターンリストに静的ファイルを提供するための適切なURLパターンを返します。次のように使います:

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf here ...

urlpatterns += staticfiles_urlpatterns()

これにより、STATIC_URL 設定が検査され、静的ファイルを適切に提供するためのビューが設定されます。 django.contrib.staticfiles がアプリディレクトリ内のファイルに加えて、どこでファイルを探せばよいかを知るために、 STATICFILES_DIRS 設定を適切に設定することを忘れないでください。

警告

このヘルパー関数は、 DEBUG が True であり、かつ STATIC_URL の設定が空でも完全なURL (例: http://static.example.com/) でもない場合にのみ動作します。

このビューは 極めて非効率的 であり、おそらく セキュリティ上の問題 も抱えています。このビューは、 ローカル開発向け であり、 本番環境で使用するべきではありません 。

「ライブテスト」をサポートするための特別なテストケース

class testing.StaticLiveServerTestCase

この unittest の TestCase サブクラスは django.test.LiveServerTestCase を拡張しています。

親と同様に、テスト対象のコードを実行し、HTTP を介してテストツール(例: Selenium、PhantomJS など)で使用するテストを記述するために使用できます。そのため、静的アセットも公開する必要があります。

しかし、上記で説明した django.contrib.staticfiles.views.serve() ビューを利用しているため、テスト実行時に staticfiles ファインダーによって配信されたアセットを透過的に上書きできます。つまり、テストのセットアップの前やその一部として collectstatic を実行する必要はありません。