staticfilesアプリ
django.contrib.staticfiles
は、各アプリケーション(および指定したその他の場所)から静的ファイルを1つの場所に収集し、本番環境で簡単に提供できるようにします。
も参照してください
静的ファイルアプリの概要といくつかの使用例については、を参照してください。 静的ファイルの管理(例: 画像、JavaScript、CSS) 。 静的ファイルの展開に関するガイドラインについては、静的ファイルの展開を参照してください。
設定
次の設定の詳細については、 staticfiles設定を参照してください。
- :setting: `STATIC_ROOT`
- :setting: `STATIC_URL`
- :setting: `STATICFILES_DIRS`
- :setting: `STATICFILES_STORAGE`
- :setting: `STATICFILES_FINDERS`
管理コマンド
django.contrib.staticfiles
は、3つの管理コマンドを公開します。
collectstatic
静的ファイルを:setting: `STATIC_ROOT` に収集します。
重複するファイル名は、デフォルトでは、テンプレート解決の動作と同様の方法で解決されます。指定された場所の1つで最初に見つかったファイルが使用されます。 混乱している場合は、:djadmin: `findstatic` コマンドを使用すると、見つかったファイルを確認できます。
後続のcollectstatic
の実行時に(STATIC_ROOT
が空でない場合)、ファイルは、STATIC_ROOT
のファイルのタイムスタンプよりも大きい変更されたタイムスタンプがある場合にのみコピーされます。 したがって、:setting: `INSTALLED_APPS` からアプリケーションを削除する場合は、古い静的ファイルを削除するためにcollectstatic --clear
オプションを使用することをお勧めします。
ファイルはを使用して検索されます :setting: `有効なファインダー ` 。 デフォルトでは、:setting: `STATICFILES_DIRS` で定義されているすべての場所と、:setting:` INSTALLED_APPS` 設定で指定されたアプリの'static'
ディレクトリを検索します。 。
:djadmin: `collectstatic` 管理コマンドは、実行のたびに:setting:` STATICFILES_STORAGE` の post_process()メソッドを呼び出し、パスのリストを渡します。管理コマンドによって検出されたもの。 また、:djadmin: `collectstatic` のすべてのコマンドラインオプションを受け取ります。 これは、デフォルトで ManifestStaticFilesStorage によって使用されます。
デフォルトでは、収集されたファイルは:setting: `FILE_UPLOAD_PERMISSIONS` からアクセス許可を受け取り、収集されたディレクトリは:setting:` 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)
次に、:setting: `STATICFILES_STORAGE` 設定を'path.to.MyStaticFilesStorage'
に設定します。
一般的に使用されるオプションは次のとおりです。
オプションの完全なリストについては、以下を実行してコマンド自身のヘルプを参照してください。
無視されたパターンリストのカスタマイズ
デフォルトの無視されたパターンリスト['CVS', '.*', '*~']
は、collectstatic
の呼び出しごとに--ignore
コマンドオプションを提供するよりも永続的な方法でカスタマイズできます。 カスタム AppConfig クラスを提供し、このクラスのignore_patterns
属性をオーバーライドして、'django.contrib.staticfiles'
を:setting: `INSTALLED_APPS` のそのクラスパスに置き換えます。設定:
from django.contrib.staticfiles.apps import StaticFilesConfig
class MyStaticFilesConfig(StaticFilesConfig):
ignore_patterns = [...] # your custom ignore list
findstatic
有効なファインダーを使用して、1つ以上の相対パスを検索します。
例えば:
デフォルトでは、一致するすべての場所が検索されます。 各相対パスの最初の一致のみを返すには、--first
オプションを使用します。
これはデバッグ支援です。 特定のパスに対して収集される静的ファイルが正確に表示されます。
--verbosity
フラグを0に設定すると、余分な出力を抑制して、パス名を取得するだけで済みます。
一方、--verbosity
フラグを2に設定すると、検索されたすべてのディレクトリを取得できます。
runserver
コアをオーバーライドします :djadmin: `runserver` コマンドの場合staticfiles
アプリは :setting: `インストール済み ` 静的ファイルの自動配信を追加します。 ファイルの提供は:setting: `MIDDLEWARE` を介して実行されません。
このコマンドは、次のオプションを追加します。
--nostatic
オプションを使用して、 staticfiles アプリでの静的ファイルの提供を完全に無効にします。 このオプションは、 staticfiles アプリがプロジェクトの:setting: `INSTALLED_APPS` 設定にある場合にのみ使用できます。
使用例:
:setting: `DEBUG` 設定がFalse
の場合でも、--insecure
オプションを使用して、 staticfiles アプリで静的ファイルを強制的に提供します。 これを使用することにより、非常に非効率的であり、おそらく安全でないであるという事実を認めます。 これはローカル開発のみを目的としており、を本番環境で使用しないでください。また、 staticfiles アプリがプロジェクトの:setting: `INSTALLED_APPS` にある場合にのみ使用できます。設定。
--insecure
は ManifestStaticFilesStorage では機能しません。
使用例:
ストレージ
StaticFilesStorage
- class storage.StaticFilesStorage
:setting: `STATIC_ROOT` 設定をベースファイルシステムの場所として使用し、:setting:` STATIC_URL` 設定を使用する、 FileSystemStorage ストレージバックエンドのサブクラスそれぞれベースURLとして。
- storage.StaticFilesStorage.post_process(paths, **options)
このメソッドがストレージで定義されている場合、実行のたびに:djadmin: `collectstatic` 管理コマンドによって呼び出され、見つかったファイルのローカルストレージとパスが辞書として渡されます。ラインオプション。 original_path, processed_path, processed
の3つの値のタプルが生成されます。 パス値は文字列であり、processed
は、値が後処理されたかどうかを示すブール値、または後処理が失敗した場合の例外です。
ManifestStaticFilesStorage は、これをバックグラウンドで使用して、パスをハッシュされた対応するパスに置き換え、キャッシュを適切に更新します。
ManifestStaticFilesStorage
- class storage.ManifestStaticFilesStorage
StaticFilesStorage ストレージバックエンドのサブクラス。ファイルのコンテンツのMD5ハッシュをファイル名に追加することにより、処理するファイル名を格納します。 たとえば、ファイルcss/styles.css
もcss/styles.55e7cbb9ba48.css
として保存されます。
このストレージの目的は、一部のページがまだそれらのファイルを参照している場合に備えて、古いファイルを提供し続けることです。 それらはあなたまたはサードパーティのプロキシサーバーによってキャッシュされるためです。 さらに、遠い将来のExpiresヘッダーをデプロイされたファイルに適用して、後続のページアクセスの読み込み時間を短縮する場合に非常に役立ちます。
ストレージバックエンドは、他の保存ファイルと一致する保存ファイルで見つかったパスを、キャッシュされたコピーのパスに自動的に置き換えます( post_process()メソッドを使用)。 これらのパスを見つけるために使用される正規表現(django.contrib.staticfiles.storage.HashedFilesMixin.patterns
)は、デフォルトで @import ルールとカスケードスタイルシートの url()ステートメントをカバーします。 。 たとえば、コンテンツを含む'css/styles.css'
ファイル
@import url("../admin/css/base.css");
ManifestStaticFilesStorage
ストレージバックエンドの url()メソッドを呼び出すことで置き換えられ、最終的に'css/styles.55e7cbb9ba48.css'
ファイルを次の内容で保存します。
@import url("../admin/css/base.27e20196a850.css");
- storage.ManifestStaticFilesStorage.max_post_process_passes
静的ファイルは、パスを置き換える必要がある他の静的ファイルを参照する可能性があるため、ファイルハッシュが収束するまで、パスを置き換える複数のパスが必要になる場合があります。 ハッシュが収束しないことによる無限ループを防ぐために(たとえば、'foo.css'
が'foo.css'
を参照する'bar.css'
を参照する場合)、後処理が破棄されるまでのパスの最大数があります。 。 参照の数が多い場合は、より多くのパスが必要になる可能性があります。 ManifestStaticFilesStorage
をサブクラス化し、max_post_process_passes
属性を設定して、パスの最大数を増やします。 デフォルトは5です。
ManifestStaticFilesStorage
を有効にするには、次の要件が満たされていることを確認する必要があります。
- :setting: `STATICFILES_STORAGE` 設定は
'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
に設定されます - :setting: `DEBUG` 設定は
False
に設定されます - :djadmin: `collectstatic` 管理コマンドを使用して、すべての静的ファイルを収集しました
MD5ハッシュの作成は、実行時にWebサイトのパフォーマンスに負担をかける可能性があるため、staticfiles
は、処理されたすべてのファイルのハッシュ名を含むマッピングをstaticfiles.json
というファイルに自動的に保存します。 これは、:djadmin: `collectstatic` 管理コマンドを実行したときに1回発生します。
- storage.ManifestStaticFilesStorage.manifest_strict
実行時にstaticfiles.json
マニフェストにファイルが見つからない場合、ValueError
が発生します。 この動作は、ManifestStaticFilesStorage
をサブクラス化し、manifest_strict
属性をFalse
に設定することで無効にできます。存在しないパスは変更されません。
:djadmin: `collectstatic` を実行する必要があるため、collectstatic
は通常のテストセットアップの一部として実行されないため、通常、テストの実行時にはこのストレージを使用しないでください。 テスト中に、:setting: `STATICFILES_STORAGE` 設定が'django.contrib.staticfiles.storage.StaticFilesStorage'
(デフォルト)のような他の設定に設定されていることを確認します。
- storage.ManifestStaticFilesStorage.file_hash(name, content=None)
ファイルのハッシュ名を作成するときに使用されるメソッド。 指定されたファイル名とコンテンツのハッシュを返す必要があります。 デフォルトでは、上記のようにコンテンツのチャンクからMD5ハッシュを計算します。 独自のハッシュアルゴリズムを使用するには、このメソッドを自由にオーバーライドしてください。
CachedStaticFilesStorage
- class storage.CachedStaticFilesStorage
バージョン2.2以降非推奨: CachedStaticFilesStorage
にはいくつかの手に負えない問題があるため、非推奨になりました。その一部を以下に概説します。 代わりに、 ManifestStaticFilesStorage またはサードパーティのクラウドストレージを使用してください。
CachedStaticFilesStorage
は ManifestStaticFilesStorage クラスと同様のクラスですが、 [と呼ばれる静的マニフェストファイルの代わりに、処理されたファイルのハッシュ名を格納するためにDjangoのキャッシュフレームワークを使用します。 X218X]。 これは主に、ファイルシステムにアクセスできない状況で役立ちます。
ストレージが使用するキャッシュバックエンドの特定のオプションを上書きする場合は、:setting: `CACHES` 設定で'staticfiles'
という名前のカスタムエントリを指定します。 'default'
キャッシュバックエンドの使用にフォールバックします。
警告
CachedStaticFilesStorage
は推奨されません。ほとんどの場合、ManifestStaticFilesStorage
の方が適しています。 CachedStaticFilesStorage
を使用すると、実行時にファイルをハッシュする必要があるため、パフォーマンスが低下します。 ネストされたファイルパスの場合、ファイルハッシュが正しいことを確認するには、複数のファイルアクセスが必要になるため、リモートファイルストレージでは、キャッシュミス時にファイルをハッシュするために数回のラウンドトリップが必要です。
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 コンテキストでレンダリングされたすべてのテンプレートコンテキストに:setting: `STATIC_URL` を追加します。
- 組み込みのテンプレートタグ:ttag: `static` は、パスを取得し、静的プレフィックス:setting:` STATIC_URL` でURL結合します。
django.contrib.staticfiles
がインストールされている場合、タグは代わりに:setting: `STATICFILES_STORAGE` のurl()
メソッドを使用します。 - 組み込みのテンプレートタグ:ttag: `get_static_prefix` は、変数として、または直接使用する静的プレフィックス:setting:` STATIC_URL` をテンプレート変数に設定します。
- 同様のテンプレートタグ:ttag: `get_media_prefix` は、:ttag:` get_static_prefix` と同様に機能しますが、:setting: `MEDIA_URL` を使用します。
静的ファイル開発ビュー
静的ファイルツールは主に、静的ファイルを本番環境に正常にデプロイするのに役立つように設計されています。 これは通常、個別の専用静的ファイルサーバーを意味し、ローカルで開発するときに混乱する多くのオーバーヘッドがあります。 したがって、staticfiles
アプリには、開発中にローカルでファイルを提供するために使用できるクイックでダーティなヘルパービューが付属しています。
- views.serve(request, path)
このビュー関数は、開発中の静的ファイルを提供します。
警告
このビューは、:setting: `DEBUG` がTrue
の場合にのみ機能します。
これは、このビューが非常に非効率的であり、おそらく安全でないであるためです。 これはローカル開発のみを目的としており、本番環境で使用しないでください。
ノート
提供されるファイルのコンテンツタイプを推測するために、このビューは、Python標準ライブラリのmimetypes
モジュールに依存しています。このモジュール自体は、基盤となるプラットフォームのマップファイルに依存しています。 このビューが特定のファイルに対して適切なコンテンツタイプを返さない場合は、プラットフォームのマップファイルを更新する必要がある可能性があります。 これは、たとえば、RedHatディストリビューションのmailcap
パッケージ、またはDebianディストリビューションのmime-support
をインストールまたは更新することで実現できます。
このビューは、:djadmin: `runserver` (:setting:` 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/'
)は、:setting: `STATIC_URL` 設定である必要があることに注意してください。
これは少し厄介なので、これを行うヘルパー関数もあります。
- urls.staticfiles_urlpatterns()
これにより、静的ファイルを提供するための適切なURLパターンが定義済みのパターンリストに返されます。 次のように使用します。
from django.contrib.staticfiles.urls import staticfiles_urlpatterns
# ... the rest of your URLconf here ...
urlpatterns += staticfiles_urlpatterns()
これにより、:setting: `STATIC_URL` 設定が検査され、それに応じて静的ファイルを提供するようにビューが接続されます。 :setting: `STATICFILES_DIRS` 設定を適切に設定して、django.contrib.staticfiles
にアプリディレクトリ内のファイルに加えてファイルを探す場所を知らせることを忘れないでください。
警告
このヘルパー関数は、:setting: `DEBUG` がTrue
であり、:setting:` STATIC_URL` 設定が空でも、次のような完全なURLでもない場合にのみ機能します。 http://static.example.com/
。
これは、このビューが非常に非効率的であり、おそらく安全でないであるためです。 これはローカル開発のみを目的としており、本番環境で使用しないでください。
「ライブテスト」をサポートするための専用テストケース
- class testing.StaticLiveServerTestCase
このユニットテストTestCaseサブクラスは、 django.test.LiveServerTestCase を拡張します。
親と同じように、テスト対象のコードを実行し、HTTPを介してテストツールで使用するテストを作成するために使用できます(例: Selenium、PhantomJSなど)。そのため、静的アセットも公開する必要があります。
ただし、上記の django.contrib.staticfiles.views.serve()ビューを利用しているため、テスト実行時にstaticfiles
によって提供されるアセットを透過的にオーバーレイできます。 ]ファインダー。 これは、テストセットアップの前または一部として:djadmin: `collectstatic` を実行する必要がないことを意味します。