{"title":"应用程序","version":"5.0","locale":"zh-hans","docname":"ref/applications","url":"/zh-hans/5.0/ref/applications/","canonical":"https://djangodocs.dev/zh-hans/5.0/ref/applications/","summary":"Django 包含一个已安装应用程序的注册表，能够存储配置和内省。它还维护着一个可用的 模型 列表。 这个注册表叫做 app ，它在 django.app 中可用： Python console Copy >>> from django.apps import apps >>> apps . get_app_config (…","html":"<span id=\"applications\"></span><h1>应用程序<a class=\"heading-anchor\" href=\"#module-django.apps\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h1>\n<p>Django 包含一个已安装应用程序的注册表，能够存储配置和内省。它还维护着一个可用的 <a class=\"reference internal\" href=\"/zh-hans/5.0/topics/db/models/\"><span class=\"doc\">模型</span></a> 列表。</p>\n<p>这个注册表叫做 <code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">app</span></code>，它在 <code class=\"xref py py-mod docutils literal notranslate\"><span class=\"pre\">django.app</span></code> 中可用：</p>\n<div class=\"code-block\" data-language=\"pycon\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Python console</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Python console code\"><code><span class=\"gp\">&gt;&gt;&gt; </span><span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">django.apps</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">apps</span>\n<span class=\"gp\">&gt;&gt;&gt; </span><span class=\"n\">apps</span><span class=\"o\">.</span><span class=\"n\">get_app_config</span><span class=\"p\">(</span><span class=\"s2\">&quot;admin&quot;</span><span class=\"p\">)</span><span class=\"o\">.</span><span class=\"n\">verbose_name</span>\n<span class=\"go\">&#39;Administration&#39;</span>\n</code></pre></div>\n<section id=\"projects-and-applications\">\n<h2>项目和应用程序<a class=\"heading-anchor\" href=\"#projects-and-applications\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>术语 <strong>项目</strong> 描述了一个 Django 网络应用。项目的 Python 包主要是由一个配置模块定义的，但它通常包含其他东西。例如，当你运行 <code class=\"docutils literal notranslate\"><span class=\"pre\">django-admin</span> <span class=\"pre\">startproject</span> <span class=\"pre\">mysite</span></code> 时，你会得到一个 <code class=\"docutils literal notranslate\"><span class=\"pre\">mysite</span></code> 项目目录，其中包含一个 <code class=\"docutils literal notranslate\"><span class=\"pre\">mysite</span></code> 的 Python 包，其中有 <code class=\"docutils literal notranslate\"><span class=\"pre\">settings.py</span></code>、<code class=\"docutils literal notranslate\"><span class=\"pre\">urls.py</span></code>、<code class=\"docutils literal notranslate\"><span class=\"pre\">asgi.py</span></code> 和 <code class=\"docutils literal notranslate\"><span class=\"pre\">wsgi.py</span></code>。该项目包经常被扩展到包括像辅助工具、CSS 和模板这样的东西，这些东西并不与特定的应用程序相关。</p>\n<p>一个 <strong>项目的根目录</strong> （包含 <code class=\"docutils literal notranslate\"><span class=\"pre\">manage.py</span></code> 文件的目录）通常是项目中所有未单独安装的应用程序的容器。</p>\n<p>术语 <strong>应用程序</strong> 指的是提供了一些功能的 Python 包。应用程序 <a class=\"reference internal\" href=\"/zh-hans/5.0/intro/reusable-apps/\"><span class=\"doc\">可在多个项目中重用</span></a>。</p>\n<p>应用程序包括模型，视图，模板，模板标签，静态文件，URL，中间件等的一些组合。它们通常使用 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 选项加入到项目中，也可以使用其他机制，如 URLconf， <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-MIDDLEWARE\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">MIDDLEWARE</span></code></a> 配置或模板继承。</p>\n<p>重要的是要理解 Django 应用程序是一组与框架各部分交互的代码。并不存在 <code class=\"docutils literal notranslate\"><span class=\"pre\">Application</span></code> 对象这种东西。但是，在一些地方，Django 需要与已安装的应用进行交互，主要是为了配置，也是为了自省。所以应用注册表为每个安装的应用在一个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 实例中维护元数据。</p>\n<p>一个项目包可以自由的作为一个应用程序并包含一些模型等（前提是，需要把它加入 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a>）。</p>\n</section>\n<section id=\"configuring-applications\">\n<span id=\"configuring-applications-ref\"></span><h2>配置应用程序<a class=\"heading-anchor\" href=\"#configuring-applications\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>要设置一个应用程序，在应用程序中创建一个 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 模块，然后在那里定义一个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 的子类。</p>\n<p>当 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 中包含一个应用程序模块的点分隔路径时，默认情况下，如果 Django 在 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 子模块中找到一个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类，它就会将该配置用于应用程序。这个行为可以通过设置 <a class=\"reference internal\" href=\"#django.apps.AppConfig.default\" title=\"django.apps.AppConfig.default\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">AppConfig.default</span></code></a> 为 <code class=\"docutils literal notranslate\"><span class=\"pre\">False</span></code> 来禁止。</p>\n<p>如果 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 模块包含多个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类，Django 会寻找一个 <a class=\"reference internal\" href=\"#django.apps.AppConfig.default\" title=\"django.apps.AppConfig.default\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">AppConfig.default</span></code></a> 为 <code class=\"docutils literal notranslate\"><span class=\"pre\">True</span></code> 的子类。</p>\n<p>如果没有找到 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类，将使用 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 基类。</p>\n<p>另外，<a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 也可以包含一个配置类的点分隔路径，以明确地指定它：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"n\">INSTALLED_APPS</span> <span class=\"o\">=</span> <span class=\"p\">[</span>\n    <span class=\"o\">...</span><span class=\"p\">,</span>\n    <span class=\"s2\">&quot;polls.apps.PollsAppConfig&quot;</span><span class=\"p\">,</span>\n    <span class=\"o\">...</span><span class=\"p\">,</span>\n<span class=\"p\">]</span>\n</code></pre></div>\n<section id=\"for-application-authors\">\n<h3>对于应用程序作者<a class=\"heading-anchor\" href=\"#for-application-authors\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>如果你正在创建一个名为 “Rock ’n’ roll” 的可插拔应用，那么这边将告诉你将如何为管理后台提供一个合适的名称：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"c1\"># rock_n_roll/apps.py</span>\n\n<span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">django.apps</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">AppConfig</span>\n\n\n<span class=\"k\">class</span><span class=\"w\"> </span><span class=\"nc\">RockNRollConfig</span><span class=\"p\">(</span><span class=\"n\">AppConfig</span><span class=\"p\">):</span>\n    <span class=\"n\">name</span> <span class=\"o\">=</span> <span class=\"s2\">&quot;rock_n_roll&quot;</span>\n    <span class=\"n\">verbose_name</span> <span class=\"o\">=</span> <span class=\"s2\">&quot;Rock ’n’ roll&quot;</span>\n</code></pre></div>\n<p>当 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 包含 <code class=\"docutils literal notranslate\"><span class=\"pre\">'rock_n_roll'</span></code> 时，<code class=\"docutils literal notranslate\"><span class=\"pre\">RockNRollConfig</span></code> 将自动加载。如果需要防止这种情况发生，可以在类定义中把 <a class=\"reference internal\" href=\"#django.apps.AppConfig.default\" title=\"django.apps.AppConfig.default\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">default</span></code></a> 设置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">False</span></code>。</p>\n<p>你可以提供多个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类来实现不同的行为。要告诉 Django 默认使用哪一个，可以在定义中把 <a class=\"reference internal\" href=\"#django.apps.AppConfig.default\" title=\"django.apps.AppConfig.default\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">default</span></code></a> 设置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">True</span></code>。如果你的用户想选择一个非默认的配置，他们必须在他们的 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 配置中用这个类的点分隔路径替换 <code class=\"docutils literal notranslate\"><span class=\"pre\">'rock_n_roll'</span></code>。</p>\n<p><a class=\"reference internal\" href=\"#django.apps.AppConfig.name\" title=\"django.apps.AppConfig.name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">AppConfig.name</span></code></a> 属性告诉 Django 这个配置适用于哪个应用。你可以定义在 <code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code> API 参考中描述任何其他属性。</p>\n<p><a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类可以在任何地方定义。<code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 惯例只是允许 Django 在 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 包含一个应用程序模块的路径而不是一个配置类的路径时自动加载它们。</p>\n<aside class=\"admonition admonition-note\" role=\"note\">\n<p class=\"admonition-title\">Note</p>\n<p>若你在应用的 <code class=\"docutils literal notranslate\"><span class=\"pre\">__init__.py</span></code> 中导入了应用注册信息，名称 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps</span></code> 会与子模块 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps</span></code> 冲突。最好的办法是将此段带入移入子模块，再导入它。折中方案是导入后取个别名:</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">django.apps</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">apps</span> <span class=\"k\">as</span> <span class=\"n\">django_apps</span>\n</code></pre></div>\n</aside>\n</section>\n<section id=\"for-application-users\">\n<h3>对于应用程序使用者<a class=\"heading-anchor\" href=\"#for-application-users\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>项目中直接使用 “Rock ’n’ roll”，其名字会是 <code class=\"docutils literal notranslate\"><span class=\"pre\">anthology</span></code>，但是你可能期望显示 “Jazz Manouche”，这需要你提供自定义配置：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"c1\"># anthology/apps.py</span>\n\n<span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">rock_n_roll.apps</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">RockNRollConfig</span>\n\n\n<span class=\"k\">class</span><span class=\"w\"> </span><span class=\"nc\">JazzManoucheConfig</span><span class=\"p\">(</span><span class=\"n\">RockNRollConfig</span><span class=\"p\">):</span>\n    <span class=\"n\">verbose_name</span> <span class=\"o\">=</span> <span class=\"s2\">&quot;Jazz Manouche&quot;</span>\n\n\n<span class=\"c1\"># anthology/settings.py</span>\n\n<span class=\"n\">INSTALLED_APPS</span> <span class=\"o\">=</span> <span class=\"p\">[</span>\n    <span class=\"s2\">&quot;anthology.apps.JazzManoucheConfig&quot;</span><span class=\"p\">,</span>\n    <span class=\"c1\"># ...</span>\n<span class=\"p\">]</span>\n</code></pre></div>\n<p>这个例子显示了位于一个名为 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 的子模块中的特定项目配置类。<a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类可以在任何地方定义。</p>\n<p>在这种情况下，<a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 必须包含配置类的点分隔路径，因为它位于应用程序之外，因此无法自动检测。</p>\n</section>\n</section>\n<section id=\"application-configuration\">\n<h2>应用程序配置<a class=\"heading-anchor\" href=\"#application-configuration\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig\">\n<em class=\"property\"><span class=\"k\"><span class=\"pre\">class</span></span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">AppConfig</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>应用程序配置对象存储了应用的元数据。某些属性可以在 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 的子类中配置。而其它 Django 设置好的配置是只读的。</p>\n</dd></dl>\n\n<section id=\"configurable-attributes\">\n<h3>可配置属性<a class=\"heading-anchor\" href=\"#configurable-attributes\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.name\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">name</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.name\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>指向此应用程序的完整的 Python 格式的路径，如 <code class=\"docutils literal notranslate\"><span class=\"pre\">'django.contrib.admin'</span></code>。</p>\n<p>此属性定义配置适用的应用程序。每个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类都必须包含此项。</p>\n<p>它必须在整个 Django 项目中唯一。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.label\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">label</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.label\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>应用程序简称，如 <code class=\"docutils literal notranslate\"><span class=\"pre\">'admin'</span></code></p>\n<p>此属性允许在两个应用标签冲突时重命名其中一个的标签名。默认是 <code class=\"docutils literal notranslate\"><span class=\"pre\">name</span></code> 的最后一段。必须是一个有效的 Python 标识符。</p>\n<p>它必须在整个 Django 项目中唯一。</p>\n<aside class=\"admonition admonition-warning\" role=\"note\">\n<p class=\"admonition-title\">Warning</p>\n<p>Changing this attribute after migrations have been applied for an\napplication will result in breaking changes to a project or, in the\ncase of a reusable app, any existing installs of that app. This is\nbecause <code class=\"docutils literal notranslate\"><span class=\"pre\">AppConfig.label</span></code> is used in database tables and migration\nfiles when referencing an app in the dependencies list.</p>\n</aside>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.verbose_name\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">verbose_name</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.verbose_name\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>应用程序容易被人理解的名称，如 “Administration”。</p>\n<p>此属性默认值为 <code class=\"docutils literal notranslate\"><span class=\"pre\">label.title()</span></code>。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.path\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">path</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.path\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>应用目录的文件系统路径，如 <code class=\"docutils literal notranslate\"><span class=\"pre\">'/usr/lib/pythonX.Y/dist-packages/django/contrib/admin'</span></code>。</p>\n<p>大多数情况下，Django 能自动检测并设置此属性，但你也能在 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类中申明此属性，显式地重写它。很少情况下要这么做；例如，若应用包是一个拥有多个路径的 <a class=\"reference internal\" href=\"#namespace-package\">命名空间</a>。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.default\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">default</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.default\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>将此属性设置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">False</span></code> 以防止 Django 自动选择配置类。当 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 只定义了一个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类，但你不想让 Django 默认使用它时，这个属性很有用。</p>\n<p>将这个属性设置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">True</span></code> 来告诉 Django 自动选择一个配置类。当 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 定义了多个 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 子类，而你希望 Django 默认使用其中一个时，这个属性很有用。</p>\n<p>默认情况下，这个属性没有设置。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.default_auto_field\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">default_auto_field</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.default_auto_field\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>隐式主键类型，用于添加到本应用中的模型。你可以用它来保持 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/models/fields/#django.db.models.AutoField\" title=\"django.db.models.AutoField\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AutoField</span></code></a> 作为第三方应用的主键类型。</p>\n<p>默认情况下，这是 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-DEFAULT_AUTO_FIELD\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">DEFAULT_AUTO_FIELD</span></code></a> 的值。</p>\n</dd></dl>\n\n</section>\n<section id=\"read-only-attributes\">\n<h3>只读属性<a class=\"heading-anchor\" href=\"#read-only-attributes\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.module\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">module</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.module\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>应用程序的根模块，如 <code class=\"docutils literal notranslate\"><span class=\"pre\">&lt;module</span> <span class=\"pre\">'django.contrib.admin'</span> <span class=\"pre\">from</span> <span class=\"pre\">'django/contrib/admin/__init__.py'&gt;</span></code>。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.models_module\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">models_module</span></span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.models_module\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>包含模型的模块，如 <code class=\"docutils literal notranslate\"><span class=\"pre\">&lt;module</span> <span class=\"pre\">'django.contrib.admin.models'</span> <span class=\"pre\">from</span> <span class=\"pre\">'django/contrib/admin/models.py'&gt;</span></code>。</p>\n<p>应用不包含 <code class=\"docutils literal notranslate\"><span class=\"pre\">models</span></code> 模块时，可能是 <code class=\"docutils literal notranslate\"><span class=\"pre\">None</span></code>。注意，数据库关联的信号，例如 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/signals/#django.db.models.signals.pre_migrate\" title=\"django.db.models.signals.pre_migrate\"><code class=\"xref py py-data docutils literal notranslate\"><span class=\"pre\">pre_migrate</span></code></a> 和 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/signals/#django.db.models.signals.post_migrate\" title=\"django.db.models.signals.post_migrate\"><code class=\"xref py py-data docutils literal notranslate\"><span class=\"pre\">post_migrate</span></code></a> 仅在应用有 <code class=\"docutils literal notranslate\"><span class=\"pre\">models</span></code> 模块时发出。</p>\n</dd></dl>\n\n</section>\n<section id=\"methods\">\n<h3>方法<a class=\"heading-anchor\" href=\"#methods\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.get_models\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">get_models</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">include_auto_created</span></span><span class=\"o\"><span class=\"pre\">=</span></span><span class=\"default_value\"><span class=\"pre\">False</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">include_swapped</span></span><span class=\"o\"><span class=\"pre\">=</span></span><span class=\"default_value\"><span class=\"pre\">False</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.get_models\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>为该应用返回一个可迭代的 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/models/instances/#django.db.models.Model\" title=\"django.db.models.Model\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">Model</span></code></a> 类。</p>\n<p>要求完整填写应用注册表。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.get_model\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">get_model</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">model_name</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">require_ready</span></span><span class=\"o\"><span class=\"pre\">=</span></span><span class=\"default_value\"><span class=\"pre\">True</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.get_model\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>返回给出的 <code class=\"docutils literal notranslate\"><span class=\"pre\">model_name</span></code> 的 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/models/instances/#django.db.models.Model\" title=\"django.db.models.Model\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">Model</span></code></a>。 <code class=\"docutils literal notranslate\"><span class=\"pre\">model_name</span></code> 是大小写敏感的。</p>\n<p>如果应用程序中不存在此模块，则抛出 <a class=\"reference external\" href=\"https://docs.python.org/3/library/exceptions.html#LookupError\" title=\"(in Python v3.14)\"><code class=\"xref py py-exc docutils literal notranslate\"><span class=\"pre\">LookupError</span></code></a> 异常。</p>\n<p>除 <code class=\"docutils literal notranslate\"><span class=\"pre\">require_ready</span></code> 参数为 <code class=\"docutils literal notranslate\"><span class=\"pre\">False</span></code> 的情况下，都必须完整设置注册信息。 <code class=\"docutils literal notranslate\"><span class=\"pre\">require_ready</span></code> 行为与 <a class=\"reference internal\" href=\"#django.apps.apps.get_model\" title=\"django.apps.apps.get_model\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">apps.get_model()</span></code></a> 一致。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.apps.AppConfig.ready\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">AppConfig.</span></span><span class=\"sig-name descname\"><span class=\"pre\">ready</span></span><span class=\"sig-paren\">(</span><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.apps.AppConfig.ready\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>子类可以重写此方法来执行类似注册信号的初始化任务。只要注册表被填满就会调用此方法。</p>\n<p>虽然你不能在定义 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 类的模型层导入模型，但可以在 <code class=\"docutils literal notranslate\"><span class=\"pre\">ready()</span></code> 中导入，通过 <code class=\"docutils literal notranslate\"><span class=\"pre\">import</span></code> 语句或 <a class=\"reference internal\" href=\"#django.apps.AppConfig.get_model\" title=\"django.apps.AppConfig.get_model\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">get_model()</span></code></a>。</p>\n<p>若你正在注册 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/signals/#module-django.db.models.signals\" title=\"django.db.models.signals: Signals sent by the model system.\"><code class=\"xref py py-mod docutils literal notranslate\"><span class=\"pre\">model</span> <span class=\"pre\">signals</span></code></a>，你可以通过字符串标签追踪发信者，而不是用模型类。</p>\n<p>举例：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">django.apps</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">AppConfig</span>\n<span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">django.db.models.signals</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">pre_save</span>\n\n\n<span class=\"k\">class</span><span class=\"w\"> </span><span class=\"nc\">RockNRollConfig</span><span class=\"p\">(</span><span class=\"n\">AppConfig</span><span class=\"p\">):</span>\n    <span class=\"c1\"># ...</span>\n\n    <span class=\"k\">def</span><span class=\"w\"> </span><span class=\"nf\">ready</span><span class=\"p\">(</span><span class=\"bp\">self</span><span class=\"p\">):</span>\n        <span class=\"c1\"># importing model classes</span>\n        <span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">.models</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">MyModel</span>  <span class=\"c1\"># or...</span>\n\n        <span class=\"n\">MyModel</span> <span class=\"o\">=</span> <span class=\"bp\">self</span><span class=\"o\">.</span><span class=\"n\">get_model</span><span class=\"p\">(</span><span class=\"s2\">&quot;MyModel&quot;</span><span class=\"p\">)</span>\n\n        <span class=\"c1\"># registering signals with the model&#39;s string label</span>\n        <span class=\"n\">pre_save</span><span class=\"o\">.</span><span class=\"n\">connect</span><span class=\"p\">(</span><span class=\"n\">receiver</span><span class=\"p\">,</span> <span class=\"n\">sender</span><span class=\"o\">=</span><span class=\"s2\">&quot;app_label.MyModel&quot;</span><span class=\"p\">)</span>\n</code></pre></div>\n<aside class=\"admonition admonition-warning\" role=\"note\">\n<p class=\"admonition-title\">Warning</p>\n<p>尽管可以向上面介绍的那样访问模型类，但是要避免在 <a class=\"reference internal\" href=\"#django.apps.AppConfig.ready\" title=\"django.apps.AppConfig.ready\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">ready()</span></code></a> 实现中与数据库交互。这包括了那些会通过 <code class=\"docutils literal notranslate\"><span class=\"pre\">django.db.connection</span></code> 执行查询 （<a class=\"reference internal\" href=\"/zh-hans/5.0/ref/models/instances/#django.db.models.Model.save\" title=\"django.db.models.Model.save\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">save()</span></code></a>， <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/models/instances/#django.db.models.Model.delete\" title=\"django.db.models.Model.delete\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">delete()</span></code></a>，管理器方法，等等）和原生查询的模型方法。你的 <a class=\"reference internal\" href=\"#django.apps.AppConfig.ready\" title=\"django.apps.AppConfig.ready\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">ready()</span></code></a> 方法会在每个管理命令初始化阶段被执行。例如，虽然测试数据库的配置与生成环境配置是分开的， <code class=\"docutils literal notranslate\"><span class=\"pre\">manager.py</span> <span class=\"pre\">test</span></code> 仍会对 <strong>生产环境</strong> 数据库执行一些查询操作。</p>\n</aside>\n<aside class=\"admonition admonition-note\" role=\"note\">\n<p class=\"admonition-title\">Note</p>\n<p>在普通的初始化进程中， <code class=\"docutils literal notranslate\"><span class=\"pre\">ready</span></code> 方法仅被 Django 调用一次。但在一些特殊情况下，特别是针对已安装应用的测试中，可以会多次调用 <code class=\"docutils literal notranslate\"><span class=\"pre\">ready</span></code>。这种情况下，在 <code class=\"docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code> 类中编写幂等方法或放入一个标志，避免那些只需运行一次的代码被多次执行。</p>\n</aside>\n</dd></dl>\n\n</section>\n<section id=\"namespace-packages-as-apps\">\n<span id=\"namespace-package\"></span><h3>命名空间包作为应用程序<a class=\"heading-anchor\" href=\"#namespace-packages-as-apps\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>没有 <code class=\"docutils literal notranslate\"><span class=\"pre\">__init__.py</span></code> 文件的 Python 包被称为 “命名空间包”，可以分布在 <code class=\"docutils literal notranslate\"><span class=\"pre\">sys.path</span></code> 上不同位置的多个目录中（见 <span class=\"target\" id=\"index-2\"></span><a class=\"pep reference external\" href=\"https://peps.python.org/pep-0420/\"><strong>PEP 420</strong></a>）。</p>\n<p>Django 应用程序需要一个单一的基础文件系统路径，Django（取决于配置）将在其中搜索模板、静态资产等。因此，只有在以下情况之一为真时，命名空间包才可能是 Django 应用程序：</p>\n<ol class=\"arabic simple\">\n<li><p>名称空间包实际上只有一个位置（即不分布在多个目录中）。</p></li>\n<li><p>用于配置应用的 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 类有一个 <a class=\"reference internal\" href=\"#django.apps.AppConfig.path\" title=\"django.apps.AppConfig.path\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">path</span></code></a> 类属性，它是 Django 将作为应用的单一基础路径的绝对目录路径。</p></li>\n</ol>\n<p>如果这些条件均不满足的话，Django 将抛出 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ImproperlyConfigured\" title=\"django.core.exceptions.ImproperlyConfigured\"><code class=\"xref py py-exc docutils literal notranslate\"><span class=\"pre\">ImproperlyConfigured</span></code></a> 错误。</p>\n</section>\n</section>\n<section id=\"application-registry\">\n<h2>应用程序注册表<a class=\"heading-anchor\" href=\"#application-registry\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<dl class=\"py data\">\n<dt class=\"sig sig-object py\" id=\"django.apps.apps\">\n<span class=\"sig-name descname\"><span class=\"pre\">apps</span></span><a class=\"heading-anchor\" href=\"#django.apps.apps\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>应用程序注册表提供以下公共 API。以下未列出的方法被视为私有方法，可能会更改，恕不另行通知。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.apps.apps.ready\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">apps.</span></span><span class=\"sig-name descname\"><span class=\"pre\">ready</span></span><a class=\"heading-anchor\" href=\"#django.apps.apps.ready\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>在注册表完全填充和调用所有 <a class=\"reference internal\" href=\"#django.apps.AppConfig.ready\" title=\"django.apps.AppConfig.ready\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">AppConfig.ready()</span></code></a> 方法后设置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">True</span></code> 的布尔属性。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.apps.apps.get_app_configs\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">apps.</span></span><span class=\"sig-name descname\"><span class=\"pre\">get_app_configs</span></span><span class=\"sig-paren\">(</span><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.apps.apps.get_app_configs\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>返回一个由 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a> 实例组成的可迭代对象</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.apps.apps.get_app_config\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">apps.</span></span><span class=\"sig-name descname\"><span class=\"pre\">get_app_config</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">app_label</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.apps.apps.get_app_config\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>返回给定 <code class=\"docutils literal notranslate\"><span class=\"pre\">app_label</span></code> 的应用程序的 <a class=\"reference internal\" href=\"#django.apps.AppConfig\" title=\"django.apps.AppConfig\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppConfig</span></code></a>。如果不存在这样的应用程序，则会引发 <a class=\"reference external\" href=\"https://docs.python.org/3/library/exceptions.html#LookupError\" title=\"(in Python v3.14)\"><code class=\"xref py py-exc docutils literal notranslate\"><span class=\"pre\">LookupError</span></code></a>。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.apps.apps.is_installed\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">apps.</span></span><span class=\"sig-name descname\"><span class=\"pre\">is_installed</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">app_name</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.apps.apps.is_installed\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>检查注册表中是否存在给定名称的应用程序。<code class=\"docutils literal notranslate\"><span class=\"pre\">app_name</span></code> 是应用程序的全名，例如 <code class=\"docutils literal notranslate\"><span class=\"pre\">'django.contrib.admin'</span></code>。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.apps.apps.get_model\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">apps.</span></span><span class=\"sig-name descname\"><span class=\"pre\">get_model</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">app_label</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">model_name</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">require_ready</span></span><span class=\"o\"><span class=\"pre\">=</span></span><span class=\"default_value\"><span class=\"pre\">True</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.apps.apps.get_model\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>返回 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/models/instances/#django.db.models.Model\" title=\"django.db.models.Model\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">Model</span></code></a> 于给定的 <code class=\"docutils literal notranslate\"><span class=\"pre\">app_label</span></code> 和 <code class=\"docutils literal notranslate\"><span class=\"pre\">model_name</span></code>。作为快捷方式，本方法也接受一个单一参数，形式为 <code class=\"docutils literal notranslate\"><span class=\"pre\">app_label.model_name</span></code>. <code class=\"docutils literal notranslate\"><span class=\"pre\">model_name</span></code> 不区分大小写。</p>\n<p>如果不存在这样的应用程序或模型，则引发 <a class=\"reference external\" href=\"https://docs.python.org/3/library/exceptions.html#LookupError\" title=\"(in Python v3.14)\"><code class=\"xref py py-exc docutils literal notranslate\"><span class=\"pre\">LookupError</span></code></a>。当调用的单个参数不包含一个点时，会引发 <a class=\"reference external\" href=\"https://docs.python.org/3/library/exceptions.html#ValueError\" title=\"(in Python v3.14)\"><code class=\"xref py py-exc docutils literal notranslate\"><span class=\"pre\">ValueError</span></code></a>。</p>\n<p>除非 <code class=\"docutils literal notranslate\"><span class=\"pre\">require_ready</span></code> 参数设置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">False</span></code>，否则要求应用注册表被完全填充。</p>\n<p>将 <code class=\"docutils literal notranslate\"><span class=\"pre\">require_ready</span></code> 设置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">False</span></code> 允许 <a class=\"reference internal\" href=\"#app-loading-process\"><span class=\"std std-ref\">在应用注册表被填充</span></a> 的时候，特别是在导入模型的第二阶段，查找模型。那么 <code class=\"docutils literal notranslate\"><span class=\"pre\">get_model()</span></code> 就和导入模型的效果一样。主要用例是用设置配置模型类，如  <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-AUTH_USER_MODEL\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">AUTH_USER_MODEL</span></code></a>。</p>\n<p>当 <code class=\"docutils literal notranslate\"><span class=\"pre\">require_ready</span></code> 为 <code class=\"docutils literal notranslate\"><span class=\"pre\">False</span></code> 时，<code class=\"docutils literal notranslate\"><span class=\"pre\">get_model()</span></code> 返回的模型类可能无法完全发挥作用（例如，可能缺少反向访问器），直到应用程序注册表完全填充。因此，最好尽可能将 <code class=\"docutils literal notranslate\"><span class=\"pre\">require_ready</span></code> 改为默认值 <code class=\"docutils literal notranslate\"><span class=\"pre\">True</span></code>。</p>\n</dd></dl>\n\n</section>\n<section id=\"initialization-process\">\n<span id=\"app-loading-process\"></span><h2>初始化进程<a class=\"heading-anchor\" href=\"#initialization-process\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<section id=\"how-applications-are-loaded\">\n<h3>应用程序是如何被加载的<a class=\"heading-anchor\" href=\"#how-applications-are-loaded\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>Django 启动后， <a class=\"reference internal\" href=\"#django.setup\" title=\"django.setup\"><code class=\"xref py py-func docutils literal notranslate\"><span class=\"pre\">django.setup()</span></code></a> 负责配置应用注册信息。</p>\n<dl class=\"py function\">\n<dt class=\"sig sig-object py\" id=\"django.setup\">\n<span class=\"sig-name descname\"><span class=\"pre\">setup</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">set_prefix</span></span><span class=\"o\"><span class=\"pre\">=</span></span><span class=\"default_value\"><span class=\"pre\">True</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.setup\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>配置 Django：</p>\n<ul class=\"simple\">\n<li><p>加载配置。</p></li>\n<li><p>设置日志。</p></li>\n<li><p>若 <code class=\"docutils literal notranslate\"><span class=\"pre\">set_prefix</span></code> 为 True，为 URL 处理器脚本增加前缀 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-FORCE_SCRIPT_NAME\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">FORCE_SCRIPT_NAME</span></code></a>，若未定义此项，则使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">/</span></code>。</p></li>\n<li><p>初始化应用程序注册。</p></li>\n</ul>\n<p>这个函数会被自动调用：</p>\n<ul class=\"simple\">\n<li><p>当通过Django的ASGI或WSGI运行HTTP服务时。</p></li>\n<li><p>调用一个管理命令时。</p></li>\n</ul>\n<p>在其他情况下，必须显式调用它，例如在纯 Python 脚本中。</p>\n<aside class=\"version-note version-changed\" data-version=\"5.0\">\n<p class=\"version-note-title\">Changed in Django 5.0</p><p>在应用程序与数据库交互之前，如果应用程序注册表尚未完全填充，则会引发 <code class=\"docutils literal notranslate\"><span class=\"pre\">RuntimeWarning</span></code>。</p>\n</aside>\n</dd></dl>\n\n<p>应用注册的初始化过程分三个阶段完成。在每个阶段，Django 根据应用在 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 中的顺序依次处理。</p>\n<ol class=\"arabic\">\n<li><p>首先，Django 导入 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 中各项条目。</p>\n<p>如果是应用配置类，Django 导入应用的根包，由其 <a class=\"reference internal\" href=\"#django.apps.AppConfig.name\" title=\"django.apps.AppConfig.name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">name</span></code></a> 属性定义。如果是 Python 包，Django 会在 <code class=\"docutils literal notranslate\"><span class=\"pre\">apps.py</span></code> 子模块中寻找应用配置，否则会创建一个默认的应用配置。</p>\n<p><em>在这情况下，你的代码不应该导入任何模型！</em></p>\n<p>换句话说，应用程序的根包和定义应用程序配置类的模块不能导入任何模型，即使是间接导入。</p>\n<p>严格来说，一旦应用配置完成加载后，Django 是允许导入模型。然而为了避免不必要的 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a>, 顺序约束。强烈建议在这个阶段不要导入任何模型。</p>\n<p>一旦这个阶段完成，可以使用 API 对应用程序配置（如 <a class=\"reference internal\" href=\"#django.apps.apps.get_app_config\" title=\"django.apps.apps.get_app_config\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">get_app_config()</span></code></a> ）进行操作。</p>\n</li>\n<li><p>然后 Django 会尝试导入每个应用程序的 <code class=\"docutils literal notranslate\"><span class=\"pre\">models</span></code> 子模块，如果有的话。</p>\n<p>你必须在你的应用程序的 <code class=\"docutils literal notranslate\"><span class=\"pre\">models.py</span></code> 或 <code class=\"docutils literal notranslate\"><span class=\"pre\">models/__init__.py</span></code> 中定义或导入所有模型。否则，应用程序注册表可能在此时没有完全填充，这可能导致 ORM 失灵。</p>\n<p>此步骤完成后，操作模型的 API，例如 <a class=\"reference internal\" href=\"#django.apps.apps.get_model\" title=\"django.apps.apps.get_model\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">get_model()</span></code></a>，就可以使用了。</p>\n</li>\n<li><p>最后 Django 会运行每个应用配置的 <a class=\"reference internal\" href=\"#django.apps.AppConfig.ready\" title=\"django.apps.AppConfig.ready\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">ready()</span></code></a> 方法。</p></li>\n</ol>\n</section>\n<section id=\"troubleshooting\">\n<span id=\"applications-troubleshooting\"></span><h3>错误调试<a class=\"heading-anchor\" href=\"#troubleshooting\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>在初始化期间，这里有一些常见的错误你可能会遇上。</p>\n<ul>\n<li><p><a class=\"reference internal\" href=\"/zh-hans/5.0/ref/exceptions/#django.core.exceptions.AppRegistryNotReady\" title=\"django.core.exceptions.AppRegistryNotReady\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AppRegistryNotReady</span></code></a>。当导入应用程序配置或模型模块触发依赖于应用程序注册表的代码时，会发生这种情况。</p>\n<p>例如， <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/utils/#django.utils.translation.gettext\" title=\"django.utils.translation.gettext\"><code class=\"xref py py-func docutils literal notranslate\"><span class=\"pre\">gettext()</span></code></a> 使用应用程序注册表来查找应用程序中的翻译目录。要在导入时进行翻译，你需要 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/utils/#django.utils.translation.gettext_lazy\" title=\"django.utils.translation.gettext_lazy\"><code class=\"xref py py-func docutils literal notranslate\"><span class=\"pre\">gettext_lazy()</span></code></a> 来代替。（使用 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/utils/#django.utils.translation.gettext\" title=\"django.utils.translation.gettext\"><code class=\"xref py py-func docutils literal notranslate\"><span class=\"pre\">gettext()</span></code></a> 会是一个 bug，因为翻译会在导入时进行，而不是在每次请求时根据活动语言进行。）</p>\n<p>在模型模块中导入时用 ORM 执行数据库查询也会触发此异常。在所有模型都可用之前，ORM 无法正常工作。</p>\n<p>如果你忘记在一个单独的 Python 脚本中调用函数 django.setup()，也会发生异常。</p>\n</li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">ImportError:</span> <span class=\"pre\">cannot</span> <span class=\"pre\">import</span> <span class=\"pre\">name</span> <span class=\"pre\">...</span></code> 如果导入序列陷入循环，就会发生这种情况。</p>\n<p>为了消除这些问题，你应该最大限度地减少模型模块之间的依赖关系，并在导入时尽可能减少复杂度。 为了避免在导入时执行代码，可以将其移入函数并缓存结果。 代码将在你首次需要结果时执行。 这个概念被称为“惰性求值”。</p>\n</li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">django.contrib.admin</span></code> 会自动在已安装的应用程序中执行 <code class=\"docutils literal notranslate\"><span class=\"pre\">admin</span></code> 模块的自动发现。为了防止这种情况发生，请将你的 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 改为包含 <code class=\"docutils literal notranslate\"><span class=\"pre\">'django.contrib.admin.app.SimpleAdminConfig'</span></code> 而不是 <code class=\"docutils literal notranslate\"><span class=\"pre\">'django.contrib.admin'</span></code>。</p></li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">RuntimeWarning:</span> <span class=\"pre\">Accessing</span> <span class=\"pre\">the</span> <span class=\"pre\">database</span> <span class=\"pre\">during</span> <span class=\"pre\">app</span> <span class=\"pre\">initialization</span> <span class=\"pre\">is</span> <span class=\"pre\">discouraged.</span></code> 此警告是在应用程序准备好之前执行的数据库查询触发的，例如在模块导入期间或在 <a class=\"reference internal\" href=\"#django.apps.AppConfig.ready\" title=\"django.apps.AppConfig.ready\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">AppConfig.ready()</span></code></a> 方法中。不鼓励这种过早的数据库查询，因为它们将在每个管理命令的启动期间运行，这会减慢项目的启动速度，可能会缓存过时的数据，甚至可能会在迁移未完成时失败。</p>\n<p>例如，一个常见的错误是进行数据库查询以填充表单字段的选择项：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"k\">class</span><span class=\"w\"> </span><span class=\"nc\">LocationForm</span><span class=\"p\">(</span><span class=\"n\">forms</span><span class=\"o\">.</span><span class=\"n\">Form</span><span class=\"p\">):</span>\n    <span class=\"n\">country</span> <span class=\"o\">=</span> <span class=\"n\">forms</span><span class=\"o\">.</span><span class=\"n\">ChoiceField</span><span class=\"p\">(</span><span class=\"n\">choices</span><span class=\"o\">=</span><span class=\"p\">[</span><span class=\"n\">c</span><span class=\"o\">.</span><span class=\"n\">name</span> <span class=\"k\">for</span> <span class=\"n\">c</span> <span class=\"ow\">in</span> <span class=\"n\">Country</span><span class=\"o\">.</span><span class=\"n\">objects</span><span class=\"o\">.</span><span class=\"n\">all</span><span class=\"p\">()])</span>\n</code></pre></div>\n<p>在上面的示例中，来自 <code class=\"docutils literal notranslate\"><span class=\"pre\">Country.objects.all()</span></code> 的查询在模块导入期间执行，因为 <code class=\"docutils literal notranslate\"><span class=\"pre\">QuerySet</span></code> 被迭代。为了避免警告，表单可以使用 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/forms/fields/#django.forms.ModelChoiceField\" title=\"django.forms.ModelChoiceField\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">ModelChoiceField</span></code></a>，如下所示：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"k\">class</span><span class=\"w\"> </span><span class=\"nc\">LocationForm</span><span class=\"p\">(</span><span class=\"n\">forms</span><span class=\"o\">.</span><span class=\"n\">Form</span><span class=\"p\">):</span>\n    <span class=\"n\">country</span> <span class=\"o\">=</span> <span class=\"n\">forms</span><span class=\"o\">.</span><span class=\"n\">ModelChoiceField</span><span class=\"p\">(</span><span class=\"n\">queryset</span><span class=\"o\">=</span><span class=\"n\">Country</span><span class=\"o\">.</span><span class=\"n\">objects</span><span class=\"o\">.</span><span class=\"n\">all</span><span class=\"p\">())</span>\n</code></pre></div>\n<p>为了更容易找到触发此警告的代码，你可以让 Python <a class=\"reference external\" href=\"https://docs.python.org/3/library/warnings.html#warning-filter\" title=\"(in Python v3.14)\"><span class=\"xref std std-ref\">将警告视为错误</span></a>，以显示堆栈跟踪，例如使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">python</span> <span class=\"pre\">-Werror</span> <span class=\"pre\">manage.py</span> <span class=\"pre\">shell</span></code>。</p>\n</li>\n</ul>\n</section>\n</section>","rootId":"module-django.apps","toc":[{"title":"项目和应用程序","anchor":"projects-and-applications","children":[]},{"title":"配置应用程序","anchor":"configuring-applications","children":[{"title":"对于应用程序作者","anchor":"for-application-authors","children":[]},{"title":"对于应用程序使用者","anchor":"for-application-users","children":[]}]},{"title":"应用程序配置","anchor":"application-configuration","children":[{"title":"可配置属性","anchor":"configurable-attributes","children":[]},{"title":"只读属性","anchor":"read-only-attributes","children":[]},{"title":"方法","anchor":"methods","children":[]},{"title":"命名空间包作为应用程序","anchor":"namespace-packages-as-apps","children":[]}]},{"title":"应用程序注册表","anchor":"application-registry","children":[]},{"title":"初始化进程","anchor":"initialization-process","children":[{"title":"应用程序是如何被加载的","anchor":"how-applications-are-loaded","children":[]},{"title":"错误调试","anchor":"troubleshooting","children":[]}]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/5.0/ref/"}],"prev":{"docname":"ref/index","title":"API 参考","url":"/zh-hans/5.0/ref/"},"next":{"docname":"ref/checks","title":"系统检查框架","url":"/zh-hans/5.0/ref/checks/"},"formats":{"html":"/zh-hans/5.0/ref/applications/","markdown":"/zh-hans/5.0/ref/applications.md","json":"/zh-hans/5.0/ref/applications.json"},"source":"https://github.com/django/django/blob/stable/5.0.x/docs/ref/applications.txt","official":"https://docs.djangoproject.com/zh-hans/5.0/ref/applications/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}