staticfiles¶django.contrib.staticfiles recopila archivos estáticos de cada una de tus aplicaciones (y cualquier otro lugar que especifiques) en un solo lugar que puede ser servido fácilmente en producción.
Ver también
Para obtener una introducción a la aplicación de archivos estáticos y algunos ejemplos de uso, vea Cómo gestionar archivos estáticos (por ejemplo, imágenes, JavaScript, CSS). Para obtener directrices sobre el despliegue de archivos estáticos, vea Cómo desplegar archivos estáticos.
Consulte staticfiles settings para detalles sobre los siguientes parámetros:
DIRECTORIO_STATICOS
URL_STATICOS
DIRECTORIOS_STATICOS
ENCUENTRADORES_STATICOS
django.contrib.staticfiles expone tres comandos de administración.
collectstatic¶Se recopilan los archivos estáticos en DIRECTORIO_STATICOS.
Los nombres de archivo duplicados se resuelven por defecto de manera similar a cómo funciona la resolución de plantillas: se utilizará el archivo que se encuentre primero en una de las ubicaciones especificadas. Si estás confundido, el comando findstatic puede ayudarte a mostrar qué archivos se encuentran.
En ejecuciones posteriores de collectstatic (si DIRECTORIO_STATICOS no está vacío), los archivos se copian solo si tienen un timestamp de modificación mayor que el timestamp del archivo en DIRECTORIO_STATICOS. Por lo tanto, si eliminaste una aplicación de INSTALLED_APPS, es una buena idea utilizar la opción collectstatic --clear para eliminar archivos estáticos obsoletos.
Los archivos se buscan utilizando los encuentradores habilitados. El valor por defecto es buscar en todas las ubicaciones definidas en DIRECTORIOS_STATICOS y en el directorio 'static' de las aplicaciones especificadas por la configuración INSTALLED_APPS.
El comando de administración collectstatic llama al método post_process() del almacenamiento de fondo de archivos estáticos staticfiles de STORAGES después de cada ejecución y pasa una lista de caminos que han sido encontrados por el comando de administración. También recibe todas las opciones de línea de comandos de collectstatic. Esto se utiliza por defecto en la clase ManifestStaticFilesStorage.
Por defecto, los archivos recolectados reciben permisos desde FILE_UPLOAD_PERMISSIONS y las carpetas recolectadas reciben permisos desde FILE_UPLOAD_DIRECTORY_PERMISSIONS. Si deseas diferentes permisos para estos archivos y/o directorios, puedes heredar de cualquiera de las clases de almacenamiento de archivos estáticos static files storage classes y especificar los parámetros file_permissions_mode y/o directory_permissions_mode, respectivamente. Por ejemplo:
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)
Luego, establece el almacenamiento de fondo de archivos estáticos staticfiles en la configuración STORAGES a “path.to.MyStaticFilesStorage”.
Algunas opciones comúnmente utilizadas son:
No preguntar al usuario para ninguna entrada.
Ignorar archivos, directorios o caminos que coincidan con este patrón de glob. Utiliza varias veces para ignorar más. Al especificar un camino, siempre utiliza barras diagonales hacia adelante, incluso en Windows.
Hacer todo excepto modificar el sistema de archivos.
Borrar los archivos existentes antes de intentar copiar o vincular el archivo original.
Crear un vínculo simbólico a cada archivo en lugar de copiarlo.
No llamar al método post_process() del almacenamiento de fondo de archivos estáticos staticfiles configurado desde STORAGES.
No ignores los patrones glob-estilo privados comunes 'CVS', '.*' y '*~'.
Para obtener una lista completa de opciones, consulta la ayuda propia del comando ejecutando:
$ python manage.py collectstatic --help
La lista de patrones por defecto ignorados, ['CVS', '.*', '*~'], se puede personalizar de manera más persistente que proporcionar la opción de comando --ignore en cada invocación de collectstatic. Proporciona una clase personalizada AppConfig , sobreescribe el atributo ignore_patterns de esta clase y reemplaza 'django.contrib.staticfiles' con la ruta de la clase en tu configuración INSTALLED_APPS:
from django.contrib.staticfiles.apps import StaticFilesConfig
class MyStaticFilesConfig(StaticFilesConfig):
ignore_patterns = [...] # your custom ignore list
findstatic¶Busca uno o más caminos relativos con los buscadores habilitados.
Ejemplo:
$ 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
Por defecto, se encuentran todos los lugares coincidentes. Para devolver solo la primera coincidencia para cada camino relativo, utiliza la opción --first:
$ python manage.py findstatic css/base.css --first
Found 'css/base.css' here:
/home/special.polls.com/core/static/css/base.css
Esto es una ayuda de depuración; te mostrará exactamente qué archivo estático se recopilará para un camino dado.
Al establecer la bandera --verbosity en 0, puedes suprimir el output adicional y obtener solo los nombres de las rutas:
$ 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
Por otro lado, al establecer la bandera --verbosity en 2, puedes obtener todos los directorios que se buscaron:
$ 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
Sobreescribe el comando de ejecución del servidor core (runserver) si la aplicación staticfiles está instalada (INSTALLED_APPS) y agrega servicio automático de archivos estáticos. El servicio de archivos no pasa por MIDDLEWARE.
El comando agrega estas opciones:
Utiliza la opción --nostatic para deshabilitar el servicio de archivos estáticos con la aplicación staticfiles en su totalidad. Esta opción solo está disponible si la aplicación staticfiles está en la configuración de la aplicación INSTALLED_APPS.
Ejemplo de uso:
$ django-admin runserver --nostatic
Utiliza la opción --insecure para obligar a servir archivos estáticos con la aplicación staticfiles incluso si la configuración de depuración (DEBUG) es False. Al utilizar esta opción, reconoces el hecho de que es grossamente ineficiente y probablemente inseguro. Esto solo se utiliza para desarrollo local y nunca debe usarse en producción y solo está disponible si la aplicación staticfiles está en la configuración de la aplicación INSTALLED_APPS.
La opción --insecure no funciona con ManifestStaticFilesStorage.
Ejemplo de uso:
$ django-admin runserver --insecure
Una subclase del almacenamiento de backend de archivos en sistema de archivos (FileSystemStorage) que utiliza la configuración STATIC_ROOT como ubicación del sistema de archivos base y la configuración STATIC_URL respectivamente como URL base.
Si este método está definido en un almacenamiento, se llama mediante el comando de administración collectstatic después de cada ejecución y se le pasa los almacenes locales y las rutas de los archivos encontrados como un diccionario, así como las opciones del comando de línea. Devuelve tuplas de tres valores: original_path, processed_path, processed. Los valores de ruta son cadenas y processed es un booleano que indica si el valor se ha postprocesado o una excepción si la post-procesación falló.
El ManifestStaticFilesStorage utiliza esto detrás de escena para reemplazar las rutas con sus contrapartidas hash y actualizar la caché adecuadamente.
ManifestStaticFilesStorage¶Una subclase del almacenamiento de fondo StaticFilesStorage que almacena los nombres de archivo que maneja agregando el MD5 hash del contenido del archivo al nombre del archivo. Por ejemplo, el archivo css/styles.css también se guardaría como css/styles.55e7cbb9ba48.css.
El propósito de este almacenamiento es mantener sirviendo los archivos antiguos en caso de que algunas páginas aún refieran a esos archivos, por ejemplo porque están cacheados por ti o un servidor proxy tercero. Además, es muy útil si deseas aplicar cabeceras Expires a futuro a los archivos desplegados para acelerar el tiempo de carga para visitas de página posteriores.
El almacenamiento de fondo reemplaza automáticamente las rutas encontradas en los archivos guardados que coincidan con otros archivos guardados con la ruta del copia cacheada (utilizando el método post_process()). Las expresiones regulares utilizadas para encontrar esas rutas (django.contrib.staticfiles.storage.HashedFilesMixin.patterns) cubren:
La regla @import y la declaración url() de los Hoja de estilo en cascada.
Los comentarios de mapa fuente en archivos CSS y JavaScript.
Si deseas utilizar las expresiones regulares experimentales para cubrir:
La importación de módulos en JavaScript.
The agregación de módulos en JavaScript.
Por ejemplo, el archivo 'css/styles.css' con este contenido:
@import url("../admin/css/base.css");
…sería reemplazado llamando al método url() del almacenamiento de fondo ManifestStaticFilesStorage, lo que finalmente guardaría un archivo 'css/styles.55e7cbb9ba48.css' con el siguiente contenido:
@import url("../admin/css/base.27e20196a850.css");
Uso del atributo HTML integrity con archivos locales
Cuando se utiliza el atributo integrity opcional dentro de etiquetas como <script> o <link>, su valor debe calcularse en función de los archivos tal como se sirven, no tal como están almacenados en el sistema de archivos. Esto es particularmente importante porque dependiendo de cómo se recopilen los archivos estáticos, su suma de comprobación puede haber cambiado (por ejemplo cuando se utiliza collectstatic). En este momento, no hay herramientas fuera de la caja disponibles para esto.
Puedes cambiar la ubicación del archivo de manifesto utilizando una clase derivada personalizada de ManifestStaticFilesStorage que establezca el argumento manifest_storage. Por ejemplo:
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)
Este atributo proporciona una sola suma de comprobación que cambia cada vez que se modifica un archivo en el manifest. Esto puede ser útil para comunicar a las aplicaciones SPAs que los activos en el servidor han cambiado (debido a una nueva implementación).
Dado que los archivos estáticos pueden referenciar otros archivos estáticos cuyas rutas deben reemplazarse, pueden ser necesarios múltiples pasos de reemplazo de rutas hasta que las sumas de comprobación converjan. Para prevenir un bucle infinito debido a que las sumas de comprobación no convergen (por ejemplo si 'foo.css' referencia 'bar.css' que a su vez refiere 'foo.css') hay un número máximo de pasos antes del post-procesamiento. En casos con un gran número de referencias, puede ser necesario un mayor número de pasos. Incrementa el número máximo de pasos estableciendo la clase derivada personalizada de ManifestStaticFilesStorage y configurando el atributo max_post_process_passes. Por defecto es 5.
Para habilitar el ManifestStaticFilesStorage, debes asegurarte de que se cumplan las siguientes condiciones:
debe estar configurado en la configuración STORAGES el almacenamiento de archivos estáticos con el valor 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
la configuración DEBUG debe estar establecida en False
debes haber recopilado todos tus archivos estáticos utilizando el comando de administración collectstatic
Dado que la creación del hash MD5 puede ser un cargo de rendimiento para tu sitio web durante la ejecución, staticfiles almacenará automáticamente la mapeación con nombres hasheados para todos los archivos procesados en un archivo llamado staticfiles.json. Esto sucede una vez cuando se ejecuta el comando collectstatic.
Si un archivo no está presente en el manifiesto de staticfiles.json durante la ejecución, se levanta un error ValueError. Puedes deshabilitar este comportamiento creando una clase que herede de ManifestStaticFilesStorage y estableciendo la propiedad manifest_strict en False – los paths inexistentes permanecerán sin cambios.
Debido a la necesidad de ejecutar collectstatic, este almacenamiento típicamente no debe usarse cuando se ejecutan pruebas ya que collectstatic no se ejecuta como parte del setup normal de las pruebas. Durante la prueba, asegúrate de que el almacenamiento de archivos estáticos en la configuración STORAGES esté establecido en algo diferente a 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage', como por ejemplo 'django.contrib.staticfiles.storage.StaticFilesStorage' (el valor predeterminado).
El método que se utiliza cuando se crea el nombre hashiado de un archivo. Necesita devolver un hash para el nombre del archivo y contenido dado. Por defecto, calcula un hash MD5 a partir de los trozos del contenido tal como se menciona arriba. Puedes sobrescribir este método para utilizar tu propio algoritmo de hashing.
ManifestFilesMixin¶Utiliza esta clase mixina con un almacenamiento personalizado para agregar el hash MD5 del contenido del archivo al nombre del archivo tal como lo hace ManifestStaticFilesStorage.
El módulo staticfiles tiene un atributo searched_locations que es una lista de direcciones de directorios en los que se han buscado los finders. Ejemplo de uso:
from django.contrib.staticfiles import finders
result = finders.find("css/base.css")
searched_locations = finders.searched_locations
Hay unos pocos otros ayudantes fuera de la aplicación staticfiles para trabajar con archivos estáticos:
El procesador de contexto django.template.context_processors.static() que agrega STATIC_URL a cada contexto de plantilla renderizado con contextos RequestContext.
El tag de plantilla incorporado static que toma una ruta y la une con el prefijo estático STATIC_URL. Si django.contrib.staticfiles está instalado, el tag utiliza el método url() del backend de almacenamiento de staticfiles desde STORAGES en su lugar.
El similar tag de plantilla incorporado get_static_prefix que puebla una variable de plantilla con el prefijo estático STATIC_URL para ser utilizado como variable o directamente.
El similar tag de plantilla incorporado get_media_prefix que funciona igual que get_static_prefix pero utiliza MEDIA_URL.
La clave staticfiles en django.core.files.storage.storages contiene una instancia lista para usar del backend de almacenamiento de staticfiles.
Los textos traducidos manteniendo todas sus etiquetas intactas son:
Esta función de vista sirve archivos estáticos en desarrollo.
Advertencia
Esta vista solo funcionará si DEBUG es True.
Eso se debe a que esta vista es grossamente ineficiente y probablemente insegura. Esto solo se pretende para el desarrollo local, y nunca debería usarse en producción.
Nota
Para adivinar los tipos de contenido de los archivos servidos, esta vista depende del módulo mimetypes de la biblioteca estándar de Python, que a su vez depende de los mapas de plataforma subyacentes. Si encuentras que esta vista no devuelve tipos de contenido apropiados para ciertos archivos, es probable que los mapas de plataforma sean incorrectos o necesiten actualizarse. Esto se puede lograr, por ejemplo, instalando o actualizando el paquete mailcap en una distribución Red Hat, mime-support en una distribución Debian, o editando las claves bajo HKEY_CLASSES_ROOT en el registro de Windows.
Esta vista está automáticamente habilitada por runserver (con un DEBUG configurado a True). Para utilizar la vista con un servidor de desarrollo local diferente, agrega el siguiente snippet al final de tu configuración de URL principal:
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),
]
Nota que el comienzo del patrón (r'^static/') debería ser tu STATIC_URL configuración.
Dado que esto es un poco finiquitado, también hay una función auxiliar que hará esto por ti:
Esto te devolverá el patrón de URL apropiado para servir archivos estáticos a tu lista de patrones definidos. Utilízalo así:
from django.contrib.staticfiles.urls import staticfiles_urlpatterns
# ... the rest of your URLconf here ...
urlpatterns += staticfiles_urlpatterns()
Esto inspeccionará tu STATIC_URL configuración y conectará la vista para servir archivos estáticos según corresponda. No olvides establecer la configuración STATICFILES_DIRS adecuadamente para permitir a django.contrib.staticfiles que sepa dónde buscar los archivos además de los directorios de aplicación.
Advertencia
Esta función auxiliar solo funcionará si DEBUG es True y tu configuración STATIC_URL no está vacía ni es una URL completa como http://static.example.com/.
Eso se debe a que esta vista es grossamente ineficiente y probablemente insegura. Esto solo se pretende para el desarrollo local, y nunca debería usarse en producción.
Esta clase de prueba hereda de django.test.LiveServerTestCase.
Al igual que su padre, puedes utilizarla para escribir pruebas que involucren ejecutar el código a probar y consumirlo con herramientas de prueba a través de HTTP (por ejemplo, Selenium, PhantomJS, etc.), por lo que es necesario publicar los activos estáticos.
Sin embargo, dado que utiliza la vista django.contrib.staticfiles.views.serve() descrita anteriormente, puede superponer transparentemente en tiempo de ejecución de las pruebas los activos proporcionados por los «finders» staticfiles. Esto significa que no necesitas ejecutar collectstatic antes o como parte del setup de tus pruebas.
may 31, 2026
Referencias en comentarios
ManifestStaticFilesStorageno ignora caminos en declaraciones que están comentadas. Este puede provocar un error en los caminos inexistentes. Debes comprobar y eliminar eventualmente los comentarios.