`staticfiles` アプリLink to this heading

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

管理コマンドLink to this heading

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

`collectstatic`Link to this heading

django-admin collectstaticLink to this definition

静的ファイルを 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 パラメータを指定します。以下に例を示します。

Code

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-inputLink to this definition: ユーザーにいかなる入力も要求せずに処理を実行します。

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

--dry-run, -nLink to this definition: ファイルシステムを変更すること以外の全てを行います。

--clear, -cLink to this definition: 既存のファイルを削除してから、元のファイルをコピーまたはリンクします。

--link, -lLink to this definition: 各ファイルをコピーする代わりに、シンボリックリンクを作成します。

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

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

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

Linux / macOS

Shell

$ python manage.py collectstatic --help

Windows

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

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

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

Code

from django.contrib.staticfiles.apps import StaticFilesConfig


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

`findstatic`Link to this heading

django-admin findstatic staticfile [staticfile ...]Link to this definition

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

例:

Linux / macOS

Shell

$ 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 --firstLink to this definition

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

Linux / macOS

Shell

$ 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

Shell

$ 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

Shell

$ 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`Link to this heading

django-admin runserver [addrport]

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

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

--nostaticLink to this definition

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

使用例:

Linux / macOS

Shell

$ django-admin runserver --nostatic

Windows

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

--insecureLink to this definition

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

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

使用例:

Linux / macOS

Shell

$ django-admin runserver --insecure

Windows

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

ストレージLink to this heading

`StaticFilesStorage`Link to this heading

class storage.StaticFilesStorageLink to this definition

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

storage.StaticFilesStorage.post_process(paths, **options)Link to this definition

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

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

`ManifestStaticFilesStorage`Link to this heading

class storage.ManifestStaticFilesStorageLink to this definition

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' を定義します。

Css

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

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

Css

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

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

Code

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)

storage.ManifestStaticFilesStorage.manifest_hashLink to this definition

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

storage.ManifestStaticFilesStorage.max_post_process_passesLink to this definition

静的ファイルは他の静的ファイルを参照することがあるため、パスを置き換える処理を複数回行う必要があります。ファイルのハッシュが収束するまでこの処理を繰り返します。無限ループを防ぐため('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_strictLink to this definition

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

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

storage.ManifestStaticFilesStorage.file_hash(name, content=None)Link to this definition

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

`ManifestFilesMixin`Link to this heading

class storage.ManifestFilesMixinLink to this definition

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

ファインダー・モジュールLink to this heading

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

Code

from django.contrib.staticfiles import finders

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

その他のヘルパーLink to this heading

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 ストレージバックエンドの使用準備が整ったインスタンスが格納されています。

静的ファイル開発ビューLink to this heading

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

views.serve(request, path)Link to this definition

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

注釈

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

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

Code

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()Link to this definition

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

Code

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

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

urlpatterns += staticfiles_urlpatterns()

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

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

class testing.StaticLiveServerTestCaseLink to this definition

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

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

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

staticfiles アプリLink to this heading#

設定Link to this heading#

管理コマンドLink to this heading#

collectstaticLink to this heading#

無視パターンリストをカスタマイズするLink to this heading#

findstaticLink to this heading#

runserverLink to this heading#

ストレージLink to this heading#

StaticFilesStorageLink to this heading#

ManifestStaticFilesStorageLink to this heading#

ManifestFilesMixinLink to this heading#

ファインダー・モジュールLink to this heading#

その他のヘルパーLink to this heading#

静的ファイル開発ビューLink to this heading#

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

`staticfiles` アプリLink to this heading

設定Link to this heading

管理コマンドLink to this heading

`collectstatic`Link to this heading

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

`findstatic`Link to this heading

`runserver`Link to this heading

ストレージLink to this heading

`StaticFilesStorage`Link to this heading

`ManifestStaticFilesStorage`Link to this heading

`ManifestFilesMixin`Link to this heading

ファインダー・モジュールLink to this heading

その他のヘルパーLink to this heading

静的ファイル開発ビューLink to this heading

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