{"title":"如何将 Django 更新至新的版本","version":"5.1","locale":"zh-hans","docname":"howto/upgrade-version","url":"/zh-hans/5.1/howto/upgrade-version/","canonical":"https://djangodocs.dev/zh-hans/5.1/howto/upgrade-version/","summary":"虽然有时是个复杂的过程，将 Django 升级到最新版有以下好处： 新功能和优化 已修复的 bug。 旧版 Django 最终将不再收到安全更新。（参考 支持的版本 ） 随着每个新 Django 发行版的发布而升级，可以使您的代码库保持最新，从而减少将来升级带来的痛苦。 有些事情需要你考虑，这有助于使升级流程尽可能顺滑。…","html":"<h1>如何将 Django 更新至新的版本<a class=\"heading-anchor\" href=\"#how-to-upgrade-django-to-a-newer-version\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h1>\n<p>虽然有时是个复杂的过程，将 Django 升级到最新版有以下好处：</p>\n<ul class=\"simple\">\n<li><p>新功能和优化</p></li>\n<li><p>已修复的 bug。</p></li>\n<li><p>旧版 Django 最终将不再收到安全更新。（参考 <a class=\"reference internal\" href=\"/zh-hans/5.1/internals/release-process/#supported-versions-policy\"><span class=\"std std-ref\">支持的版本</span></a>）</p></li>\n<li><p>随着每个新 Django 发行版的发布而升级，可以使您的代码库保持最新，从而减少将来升级带来的痛苦。</p></li>\n</ul>\n<p>有些事情需要你考虑，这有助于使升级流程尽可能顺滑。</p>\n<section id=\"required-reading\">\n<h2>必读内容<a class=\"heading-anchor\" href=\"#required-reading\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>若这是你第一次进行升级操作，那么阅读 <a class=\"reference internal\" href=\"/zh-hans/5.1/internals/release-process/\"><span class=\"doc\">不同发行进程的指南</span></a> 就非常有用。</p>\n<p>随后，您应该熟悉新的 Django 版本中所进行的更改：</p>\n<ul class=\"simple\">\n<li><p>阅读当前版本之后的每个“最终”版本的 <a class=\"reference internal\" href=\"/zh-hans/5.1/releases/\"><span class=\"doc\">发行说明</span></a> ，包括计划升级的版本。</p></li>\n<li><p>阅读 <a class=\"reference internal\" href=\"/zh-hans/5.1/internals/deprecation/\"><span class=\"doc\">过期时间表</span></a> 获取相关版本信息。</p></li>\n</ul>\n<p>特别注意向前兼容修改，清楚了解成功的升级需要做什么。</p>\n<p>若你更新的版本跨度超过一个特性版本（例如从 2.0 更新到 2.2），通常增量更新（从 2.0 到 2.1 再到 2.2）每个版本会比一次性更新更容易。对于每个发布特性，使用最新的补丁版本（例如，对于 2.1，使用 2.1.15）。</p>\n<p>从一个长期支持（LTS）版本更新至下一个长期更新版本时，特别推荐同样的增量更新方法。</p>\n</section>\n<section id=\"dependencies\">\n<h2>依赖<a class=\"heading-anchor\" href=\"#dependencies\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>大多数情况下，将 Django 的依赖升至最新版本是必要的。若 Django 版本是最近发布的，但某些依赖没有很好适配，这些依赖可能无法支持最新版的 Django。这种情况下，你只能等新版本的依赖发布。</p>\n</section>\n<section id=\"resolving-deprecation-warnings\">\n<h2>处理过期警告<a class=\"heading-anchor\" href=\"#resolving-deprecation-warnings\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>在升级前，将使用当前 Django 版本引发的过期警告解决掉是个不错的注意。在升级前修复这些警告能确保你了解代码中哪些部分需要修改。</p>\n<p>在 Python 中，过期警告默认是静默的。你必须用 Python 的命令行选项 <code class=\"docutils literal notranslate\"><span class=\"pre\">-Wa</span></code> 或 <span class=\"target\" id=\"index-2\"></span><a class=\"reference external\" href=\"https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS\" title=\"(in Python v3.14)\"><code class=\"xref std std-envvar docutils literal notranslate\"><span class=\"pre\">PYTHONWARNINGS</span></code></a> 环境变量将其打开。例如，在运行测试时显示警告：</p>\n<div class=\"console\" data-console><div class=\"console-panel\" data-platform=\"unix\"><p class=\"console-label\" id=\"console-0-unix-label\">Linux / macOS</p><div class=\"code-block\" data-language=\"console\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Shell</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=\"Shell code\"><code><span class=\"gp\">$ </span>python<span class=\"w\"> </span>-Wa<span class=\"w\"> </span>manage.py<span class=\"w\"> </span><span class=\"nb\">test</span>\n</code></pre></div>\n</div><div class=\"console-panel\" data-platform=\"windows\"><p class=\"console-label\" id=\"console-0-windows-label\">Windows</p><div class=\"code-block\" data-language=\"doscon\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Windows</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=\"Windows shell\"><code><span class=\"gp\">...\\&gt;</span> py -Wa manage.py test\n</code></pre></div></div></div>\n<p>如果你没有使用 Django 测试运行器，还需要确保不捕获任何控制台输出，以防止隐藏废弃警告。例如，如果你使用 <a class=\"reference external\" href=\"https://docs.pytest.org/\">pytest</a>：</p>\n<div class=\"code-block\" data-language=\"console\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Shell</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=\"Shell code\"><code><span class=\"gp\">$ </span><span class=\"nv\">PYTHONWARNINGS</span><span class=\"o\">=</span>always<span class=\"w\"> </span>pytest<span class=\"w\"> </span>tests<span class=\"w\"> </span>--capture<span class=\"o\">=</span>no\n</code></pre></div>\n<p>在继续升级流程前处理当前 Django 版本报告的所有过期警告。</p>\n<p>第三方应用可能会出于兼容多版本 Django 目的使用过期 APIs，所以你安装的应用报告的过期警告可能并不是问题。若某个包不支持最新版的 Django，考虑为其创建一个 issue 或发起一个 pull request。</p>\n</section>\n<section id=\"installation\">\n<h2>安装<a class=\"heading-anchor\" href=\"#installation\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>准备好后，就是 <a class=\"reference internal\" href=\"/zh-hans/5.1/topics/install/\"><span class=\"doc\">安装新版 Django</span></a> 的时候。若你正使用 <a class=\"reference external\" href=\"https://docs.python.org/3/library/venv.html#module-venv\" title=\"(in Python v3.14)\"><code class=\"xref py py-mod docutils literal notranslate\"><span class=\"pre\">virtual</span> <span class=\"pre\">environment</span></code></a>，且这是一次关键性升级，你可能想要先配置一个包含所有依赖的环境。</p>\n<p>若你用 <a class=\"reference external\" href=\"https://pip.pypa.io/\">pip</a> 安装 Django，你可以使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">--upgrade</span></code> 或 <code class=\"docutils literal notranslate\"><span class=\"pre\">-U</span></code> 标志：</p>\n<div class=\"console\" data-console><div class=\"console-panel\" data-platform=\"unix\"><p class=\"console-label\" id=\"console-1-unix-label\">Linux / macOS</p><div class=\"code-block\" data-language=\"console\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Shell</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=\"Shell code\"><code><span class=\"gp\">$ </span>python<span class=\"w\"> </span>-m<span class=\"w\"> </span>pip<span class=\"w\"> </span>install<span class=\"w\"> </span>-U<span class=\"w\"> </span>Django\n</code></pre></div>\n</div><div class=\"console-panel\" data-platform=\"windows\"><p class=\"console-label\" id=\"console-1-windows-label\">Windows</p><div class=\"code-block\" data-language=\"doscon\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Windows</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=\"Windows shell\"><code><span class=\"gp\">...\\&gt;</span> py -m pip install -U Django\n</code></pre></div></div></div>\n</section>\n<section id=\"testing\">\n<h2>测试<a class=\"heading-anchor\" href=\"#testing\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>当环境准备好后，先为应用 <a class=\"reference internal\" href=\"/zh-hans/5.1/topics/testing/overview/\"><span class=\"doc\">运行完整的测试套件</span></a>。再说一次，将过期警告开关打开很有用，这样就能在测试输出中看到过期警告（若你用 <code class=\"docutils literal notranslate\"><span class=\"pre\">manage.py</span> <span class=\"pre\">runserver</span></code> 手动测试，也能有该标志）：</p>\n<div class=\"console\" data-console><div class=\"console-panel\" data-platform=\"unix\"><p class=\"console-label\" id=\"console-2-unix-label\">Linux / macOS</p><div class=\"code-block\" data-language=\"console\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Shell</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=\"Shell code\"><code><span class=\"gp\">$ </span>python<span class=\"w\"> </span>-Wa<span class=\"w\"> </span>manage.py<span class=\"w\"> </span><span class=\"nb\">test</span>\n</code></pre></div>\n</div><div class=\"console-panel\" data-platform=\"windows\"><p class=\"console-label\" id=\"console-2-windows-label\">Windows</p><div class=\"code-block\" data-language=\"doscon\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Windows</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=\"Windows shell\"><code><span class=\"gp\">...\\&gt;</span> py -Wa manage.py test\n</code></pre></div></div></div>\n<p>在你运行测试，并修复所有问题后。由于你刚看了发布说明，可能现在也是重构代码，消除所有过期警告，尝尝 Django 最新功能特性的好时机。</p>\n</section>\n<section id=\"deployment\">\n<h2>部署<a class=\"heading-anchor\" href=\"#deployment\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>当你十分确信你的应用能兼容新版 Django 时，你就准备好去往下一步， <a class=\"reference internal\" href=\"/zh-hans/5.1/howto/deployment/\"><span class=\"doc\">部署</span></a> 升级后的 Django 工程。</p>\n<p>若你使用 Django 提供的缓存，你需要考虑在升级后清空缓存。否则，你可能会卷入麻烦中，举个例子，若你缓存了 pickled 对象，而这些对象并不能确保跨版本 pickle 兼容。一个过期兼容性例子是缓存 pickled <a class=\"reference internal\" href=\"/zh-hans/5.1/ref/request-response/#django.http.HttpResponse\" title=\"django.http.HttpResponse\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">HttpResponse</span></code></a> 对象，不论是直接或间接由 <a class=\"reference internal\" href=\"/zh-hans/5.1/topics/cache/#django.views.decorators.cache.cache_page\" title=\"django.views.decorators.cache.cache_page\"><code class=\"xref py py-func docutils literal notranslate\"><span class=\"pre\">cache_page()</span></code></a> 装饰器创建。</p>\n</section>","rootId":"how-to-upgrade-django-to-a-newer-version","toc":[{"title":"必读内容","anchor":"required-reading","children":[]},{"title":"依赖","anchor":"dependencies","children":[]},{"title":"处理过期警告","anchor":"resolving-deprecation-warnings","children":[]},{"title":"安装","anchor":"installation","children":[]},{"title":"测试","anchor":"testing","children":[]},{"title":"部署","anchor":"deployment","children":[]}],"breadcrumbs":[{"docname":"howto/index","title":"如何引导","url":"/zh-hans/5.1/howto/"}],"prev":{"docname":"howto/delete-app","title":"如何删除一个 Django 应用","url":"/zh-hans/5.1/howto/delete-app/"},"next":{"docname":"howto/windows","title":"如何在 Windows 上安装 Django","url":"/zh-hans/5.1/howto/windows/"},"formats":{"html":"/zh-hans/5.1/howto/upgrade-version/","markdown":"/zh-hans/5.1/howto/upgrade-version.md","json":"/zh-hans/5.1/howto/upgrade-version.json"},"source":"https://github.com/django/django/blob/stable/5.1.x/docs/howto/upgrade-version.txt","official":"https://docs.djangoproject.com/zh-hans/5.1/howto/upgrade-version/","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"]}