Django Debug Toolbar 配置详解

Django Debug Toolbar 配置详解

django-debug-toolbar jazzband/django-debug-toolbar: 是一个用于 Django 开发的调试工具栏，可以提供多种调试工具和性能分析功能，可以用于 Django 应用程序的开发和调试。 项目地址: https://gitcode.com/gh_mirrors/dj/django-debug-toolbar

前言

Django Debug Toolbar 是 Django 开发过程中不可或缺的调试工具，它提供了丰富的面板来展示请求处理过程中的各种信息。本文将深入解析 Django Debug Toolbar 的配置选项，帮助开发者根据项目需求进行个性化定制。

基本配置原则

在开始配置前，需要明确一个重要原则：不要盲目复制默认配置。Django Debug Toolbar 已经提供了合理的默认值，这些默认值适用于大多数 Django 项目。直接复制默认配置不仅无用，还可能阻碍你在未来版本中获得更好的默认设置。

核心配置选项

1. DEBUG_TOOLBAR_PANELS

这个设置用于指定要在工具栏中显示的面板列表，其工作方式类似于 Django 的 MIDDLEWARE 设置。默认包含以下面板：

DEBUG_TOOLBAR_PANELS = [
    'debug_toolbar.panels.history.HistoryPanel',
    'debug_toolbar.panels.versions.VersionsPanel',
    'debug_toolbar.panels.timer.TimerPanel',
    'debug_toolbar.panels.settings.SettingsPanel',
    'debug_toolbar.panels.headers.HeadersPanel',
    'debug_toolbar.panels.request.RequestPanel',
    'debug_toolbar.panels.sql.SQLPanel',
    'debug_toolbar.panels.staticfiles.StaticFilesPanel',
    'debug_toolbar.panels.templates.TemplatesPanel',
    'debug_toolbar.panels.alerts.AlertsPanel',
    'debug_toolbar.panels.cache.CachePanel',
    'debug_toolbar.panels.signals.SignalsPanel',
    'debug_toolbar.panels.redirects.RedirectsPanel',
    'debug_toolbar.panels.profiling.ProfilingPanel',
]

通过这个设置，你可以：

• 添加默认未启用的内置面板
• 添加第三方面板
• 移除不需要的内置面板
• 调整面板的显示顺序

2. DEBUG_TOOLBAR_CONFIG

这是一个字典，包含所有其他配置选项，其中一些适用于工具栏本身，另一些则针对特定面板。

工具栏通用选项

1. DISABLE_PANELS
   默认禁用某些面板（但仍显示），如性能分析面板和重定向面板。

2. INSERT_BEFORE
   默认值为 '</body>'，指定工具栏在 HTML 中插入的位置。

3. IS_RUNNING_TESTS
   检测是否在运行测试，默认情况下会阻止在测试时显示工具栏。

4. RENDER_PANELS
   控制面板内容的渲染方式：

   • False：面板内容保存在服务器内存中，按需加载
   • True：禁用历史面板并在每个页面中渲染所有面板
   • None（默认）：自动根据 WSGI 容器是否运行多进程来决定

5. RESULTS_CACHE_SIZE
   工具栏在内存中保存的结果数量，默认为 25。

6. ROOT_TAG_EXTRA_ATTRS
   用于避免与客户端框架冲突，例如与 Angular.js 一起使用时可以设置为 'ng-non-bindable'。

7. SHOW_COLLAPSED
   控制工具栏默认是否折叠，默认为 False。

8. SHOW_TOOLBAR_CALLBACK
   决定是否显示工具栏的回调函数，默认检查 DEBUG=True 且请求 IP 在 INTERNAL_IPS 中。

   安全警告：不要在生产环境中使用自定义回调，因为这可能导致安全风险，特别是当 SECRET_KEY 泄露时，攻击者可能通过 SQL 面板执行任意 SQL。

9. TOOLBAR_LANGUAGE
   指定工具栏的显示语言，可与应用语言不同。

10. UPDATE_ON_FETCH
    控制工具栏是否更新最新的 AJAX 请求，对使用 htmx 等技术的项目特别有用。

面板特定选项

1. EXTRA_SIGNALS
   信号面板：添加项目中的自定义信号。

2. ENABLE_STACKTRACES
   SQL 和缓存面板：是否显示堆栈跟踪，启用会增加 CPU 使用率。

3. ENABLE_STACKTRACES_LOCALS
   SQL 和缓存面板：是否显示堆栈跟踪中的局部变量，会显著增加 CPU 使用率并可能暴露敏感信息。

4. HIDE_IN_STACKTRACES
   SQL 和缓存面板：隐藏指定模块的堆栈跟踪条目，减少 DOM 大小和渲染延迟。

5. PRETTIFY_SQL
   SQL 面板：是否美化 SQL 输出，启用可能导致长查询的渲染变慢。

6. PROFILER_ 系列设置*
   性能分析面板：控制分析深度、包含的项目代码和显示阈值。

7. SHOW_TEMPLATE_CONTEXT
   模板面板：是否显示模板上下文，对于大型上下文或延迟数据结构建议禁用。

8. SKIP_TEMPLATE_PREFIXES
   模板面板：跳过指定前缀的模板，默认跳过 Django 表单小部件模板。

9. SQL_WARNING_THRESHOLD
   SQL 面板：高亮显示执行时间超过此阈值（毫秒）的查询。

主题定制

Django Debug Toolbar 使用 CSS 变量来定义字体和颜色，使得定制更加方便。例如，要更改默认字体为 Roboto，可以创建一个模板覆盖：

{% extends 'debug_toolbar/base.html' %}

{% block css %}{{ block.super }}
<style>
    :root {
        --djdt-font-family-primary: 'Roboto', sans-serif;
    }
</style>
{% endblock %}

配置示例

以下是一个自定义配置示例（注意：这只是一个示例，不一定适合你的项目）：

DEBUG_TOOLBAR_CONFIG = {
    # 工具栏选项
    'RESULTS_CACHE_SIZE': 3,
    'SHOW_COLLAPSED': True,
    # 面板选项
    'SQL_WARNING_THRESHOLD': 100,  # 毫秒
}

总结

Django Debug Toolbar 提供了丰富的配置选项，允许开发者根据项目需求进行精细调整。在大多数情况下，使用默认配置即可满足需求。只有在确实需要时才应进行自定义配置，并始终注意潜在的性能和安全影响。

django-debug-toolbar jazzband/django-debug-toolbar: 是一个用于 Django 开发的调试工具栏，可以提供多种调试工具和性能分析功能，可以用于 Django 应用程序的开发和调试。 项目地址: https://gitcode.com/gh_mirrors/dj/django-debug-toolbar