生产环境Django collectstatic路径冲突处理及多UI包兼容问题

问题背景 #

使用Django 4.2集成Django-JET-reboot分支作为后台管理包，每次执行collectstatic时会抛出**"Found another file with the destination path"**警告，导致部署耗时增加。经排查，是Django-JET的CSS/JS文件与django.contrib.admin的同名文件冲突，现提出两个问题：

1. 这种情况是否属于预期行为且无风险？有没有更优的处理方案？
2. 能否集成其他UI修改类包（比如Black Dashboard Django）？是否只需调整INSTALLED_APPS顺序，将其放在jet之后即可避免覆盖JET的文件？

警告信息详情 #

Found another file with the destination path 'admin/css/base.css'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/css/changelists.css'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/css/dashboard.css'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/css/forms.css'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/css/login.css'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/css/rtl.css'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/css/widgets.css'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/js/SelectFilter2.js'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/js/admin/DateTimeShortcuts.js'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.
Found another file with the destination path 'admin/js/admin/RelatedObjectLookups.js'. It will be ignored since only the first encountered file is collected. If this is not what you want, make sure every static file has a unique path.

findstatic命令输出结果 #

Found 'admin/css/base.css' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/css/base.css
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/css/base.css
Found 'admin/css/changelists.css' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/css/changelists.css
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/css/changelists.css
Found 'admin/css/dashboard.css' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/css/dashboard.css
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/css/dashboard.css
Found 'admin/css/forms.css' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/css/forms.css
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/css/forms.css
Found 'admin/css/login.css' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/css/login.css
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/css/login.css
Found 'admin/css/rtl.css' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/css/rtl.css
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/css/rtl.css
Found 'admin/css/widgets.css' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/css/widgets.css
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/css/widgets.css
Found 'admin/js/SelectFilter2.js' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/js/SelectFilter2.js
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/js/SelectFilter2.js
Found 'admin/js/admin/DateTimeShortcuts.js' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/js/admin/DateTimeShortcuts.js
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/js/admin/DateTimeShortcuts.js
Found 'admin/js/admin/RelatedObjectLookups.js' here:
  /usr/local/lib/python3.10/site-packages/jet/static/admin/js/admin/RelatedObjectLookups.js
  /usr/local/lib/python3.10/site-packages/django/contrib/admin/static/admin/js/admin/RelatedObjectLookups.js

当前配置 #

INSTALLED_APPS

DJANGO_APPS = [
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.sites",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "jet",
    "django.contrib.admin",
    "django.forms",
]

THIRD_PARTY_APPS = [
    "django_filters",
    "crispy_forms",
    "crispy_bootstrap5",
    "allauth",
    "allauth.account",
    "allauth.socialaccount",
    "rest_framework",
    # 'rest_framework_json_api',
    "django_extensions",
    "rest_framework.authtoken",
    "corsheaders",
    "drf_spectacular",
]

静态文件配置

# STATIC
# ------------------------------------------------------------------------------
ROOT_DIR = Path(__file__).resolve(strict=True).parent.parent.parent
APPS_DIR = ROOT_DIR / "backend" #Main Django App Folder Name

STATIC_ROOT = str(ROOT_DIR / "staticfiles")

STATIC_URL = "/static/"

STATICFILES_DIRS = [
    str(APPS_DIR / "static"),
]

STATICFILES_FINDERS = [
    "django.contrib.staticfiles.finders.FileSystemFinder",
    "django.contrib.staticfiles.finders.AppDirectoriesFinder",
]

问题解答 #

1. 静态文件冲突的风险与优化方案 #

是否属于预期行为且无风险？

这是预期行为，Django-JET的设计就是通过覆盖原生Admin的静态文件实现UI定制，你已经把jet放在django.contrib.admin之前，Django会优先收集JET的文件、忽略原生Admin的同名文件，完全符合JET的功能需求，功能上没有风险。但警告会增加collectstatic的执行时间，因为Django会遍历所有静态文件路径并检查冲突。

更优处理实践

有几种方案可以解决这个问题：

• 使用--ignore参数跳过原生Admin静态文件：
  执行collectstatic时添加参数，直接忽略django.contrib.admin的静态目录：

  python manage.py collectstatic --ignore="admin" --ignore="django/contrib/admin/static/admin"
  

  注意需要测试参数是否匹配你的环境路径，确保只跳过原生Admin的静态文件，不影响其他资源。

• 自定义静态文件查找器：
  编写一个自定义查找器，跳过django.contrib.admin的静态文件，只收集JET和项目静态文件。示例如下：

  # 在项目的某个app中创建finders.py
  from django.contrib.staticfiles.finders import AppDirectoriesFinder
  from django.contrib.admin import apps as admin_apps
  
  class SkipAdminStaticFinder(AppDirectoriesFinder):
      def list(self, ignore_patterns):
          original_list = super().list(ignore_patterns)
          # 过滤掉django.contrib.admin的静态文件
          return [item for item in original_list if admin_apps.AdminConfig.name not in item[0]]
  

  然后在STATICFILES_FINDERS中替换默认的AppDirectoriesFinder：

  STATICFILES_FINDERS = [
      "django.contrib.staticfiles.finders.FileSystemFinder",
      "your_app.finders.SkipAdminStaticFinder",
  ]
  

• 将JET静态文件复制到本地项目目录：
  把JET的admin静态文件夹复制到你的项目backend/static目录下，这样FileSystemFinder会优先加载本地文件，同时可以完全控制静态文件内容，也避免了第三方包的静态文件冲突。

2. 集成其他UI修改类包的可行性 #

可以集成其他UI类包，但仅调整INSTALLED_APPS顺序不一定能完全解决问题，需要注意以下几点：

• 静态文件优先级：Django会按照INSTALLED_APPS的顺序收集静态文件，后加入的app如果有同名静态文件，会被先加入的app覆盖。所以如果要让新的UI包覆盖JET的文件，需要把它放在jet之前；如果想保留JET的文件，把它放在jet之后。
• 兼容性问题：不同的Admin UI定制包可能修改同一套静态文件，甚至可能有模板层面的冲突。比如Black Dashboard Django可能不仅修改静态文件，还会重写Admin模板，这时候需要测试两者的兼容性，避免出现样式错乱或功能失效的情况。
• 建议：如果要替换JET，直接移除jet并安装新的UI包；如果要叠加功能，先在测试环境验证兼容性，再调整INSTALLED_APPS顺序并测试静态文件加载是否符合预期。

内容的提问来源于stack exchange，提问作者Jay