Django与MySQL版本冲突：从NotSupportedError到升级与降级解决方案

1. 问题现场：当Django告诉你MySQL太老了

“Django.db.utils.NotSupportedError: MySQL 8 or later is required (found 5.7.26).”

如果你在启动Django项目，运行python manage.py migrate或者python manage.py runserver时，控制台突然抛出这么一行红字，心里多半会咯噔一下。这行错误信息非常直白：你的Django项目要求MySQL数据库的版本至少是8.0，但系统检测到的却是5.7.26。对于很多从老项目升级过来，或者本地开发环境沿用旧版本MySQL的朋友来说，这是一个典型的“版本墙”问题。

我遇到过不止一次，尤其是在接手一些历史遗留项目，或者尝试在新机器上复现一个几年前的项目环境时。MySQL 5.7是一个相当长寿且稳定的版本，至今仍有大量生产环境在使用。而Django作为一个持续演进的Web框架，其内置的数据库后端为了支持新特性（比如更好的JSON字段支持、更优的查询优化等），会逐步提高对数据库最低版本的要求。这个错误就是这种演进冲突的直接体现。它不是一个配置错误，而是一个硬性的版本不兼容声明，意味着在MySQL 5.7上，当前Django版本的某些功能或安全要求无法被满足，框架直接拒绝工作。

这个问题的核心不在于Django代码写错了，也不在于你的MySQL 5.7安装有问题，而在于两者之间的“协议”不匹配了。解决思路无非两条：要么把MySQL升级到8.0或更高版本以满足Django的要求；要么把Django（或相关驱动）降级到一个兼容MySQL 5.7的版本。对于新项目或计划长期维护的项目，升级MySQL通常是更推荐的选择，因为能获得更好的性能、安全性和功能支持。当然，如果因为某些原因无法升级数据库（比如受制于老旧的生产环境或第三方服务），那么调整Django版本就是唯一的出路。

2. 根因探析：为什么Django 4+开始“嫌弃”MySQL 5.7？

要理解这个错误，我们不能停留在表面，得挖一挖Django和MySQL版本迭代背后的故事。Django从4.0版本开始，官方将django.db.backends.mysql后端对MySQL的最低要求从5.6提升到了8.0。这个决定不是拍脑袋来的，背后有几个关键的技术驱动因素。

首先，是JSON字段的完整支持。MySQL从5.7开始引入了原生的JSON数据类型，这是一个巨大的进步。但是，5.7版本的JSON函数和操作符支持还比较基础，存在一些限制和性能问题。而MySQL 8.0对JSON的支持进行了大幅增强，增加了更多函数（如JSON_TABLE），优化了存储格式和查询性能。Django的JSONField在底层需要依赖数据库的这些原生能力来实现高效的查询和验证。为了提供更强大、更可靠的JSON字段功能，Django选择将基线定在支持更完善的MySQL 8.0上。

其次，涉及到默认字符集和排序规则。MySQL 5.7的默认字符集是latin1，而MySQL 8.0的默认字符集是utf8mb4。utf8mb4才是真正完整的UTF-8编码，支持所有的Unicode字符（包括emoji表情）。在Web全球化应用的今天，使用utf8mb4几乎是标配。Django为了确保新建数据库和表默认就能获得最好的Unicode支持，减少因字符集导致的乱码问题，自然倾向于拥抱以utf8mb4为默认值的MySQL 8.0。

再者，是窗口函数等高级SQL特性。窗口函数（Window Functions）是SQL:2003标准中引入的强大功能，用于进行复杂的行间计算（如排名、累计求和、移动平均等）。MySQL从8.0开始才原生支持窗口函数。虽然Django的ORM不一定直接暴露所有窗口函数语法，但其查询引擎的持续优化和未来可能引入的高级查询特性，会依赖于数据库对这些现代SQL标准的支持。将最低版本设为8.0，为框架未来的发展扫清了障碍。

最后，安全性和维护周期也是重要考量。MySQL 5.7已于2023年10月结束了其扩展支持阶段。这意味着Oracle不再为5.7提供常规的错误修复和安全补丁。对于Django这样一个强调安全性的框架来说，鼓励甚至强制用户使用处于活跃支持周期的数据库版本，是负责任的表现，可以降低用户项目整体的安全风险。

所以，当你看到这个NotSupportedError时，其实是Django在说：“老朋友，为了能用上更强大的功能（JSON、更好的UTF-8支持），为了代码更安全，也为了我能轻装上阵继续发展，咱们得一起往前走了，MySQL 5.7这条船，我不能再坐了。”

3. 解决方案一：升级MySQL至8.0（推荐路径）

对于大多数情况，尤其是新项目或可以掌控数据库环境的情况，升级到MySQL 8.0是最一劳永逸的方案。它不仅解决了兼容性问题，还能带来性能提升和新特性。升级过程需要谨慎，尤其是生产环境，但本地开发环境的升级相对简单。

3.1 本地开发环境升级操作指南

在本地开发机器上（以macOS和Windows为例），升级MySQL通常意味着安装一个新版本，并迁移旧数据。务必先备份所有数据库！

对于macOS（使用Homebrew）：如果你之前用Homebrew安装了MySQL 5.7，升级过程相对清晰。

1. 停止旧服务：首先停止正在运行的MySQL 5.7服务。

   brew services stop mysql@5.7

2. 安装MySQL 8.0：使用Homebrew安装最新的MySQL 8.0。

   brew install mysql

   这通常会安装最新稳定版（目前是8.0系列）。Homebrew可能会提示你，它安装了mysql而不是mysql@5.7，旧版本公式已被移除。
3. 启动新服务并升级数据：安装完成后，启动MySQL 8.0服务。首次启动时，MySQL 8.0可能会检测到来自5.7版本的数据目录，并提示你需要执行升级程序。按照Homebrew的输出提示操作，通常命令类似于：

   brew services start mysql mysql_upgrade -u root -p

   执行mysql_upgrade会检查所有数据库表，并将其结构升级到与MySQL 8.0兼容。过程中可能需要输入root密码。
4. 验证版本：连接MySQL，检查版本。

   mysql -u root -p -e "SELECT VERSION();"

   应该显示8.0.x。

对于Windows（使用MySQL Installer或ZIP包）：Windows上的升级，更推荐使用MySQL官方Installer，它提供了较好的升级向导。

1. 备份数据：使用mysqldump命令或工具（如MySQL Workbench, phpMyAdmin）完整备份所有数据库。

   mysqldump -u root -p --all-databases > backup_all.sql

2. 卸载MySQL 5.7：通过“控制面板”->“程序和功能”找到MySQL 5.7并卸载。注意：卸载程序通常会询问是否移除数据文件，为了干净升级，建议选择“是”，删除所有数据。因为我们有备份，所以不用担心。如果你选择保留数据文件，后续手动配置会复杂一些。
3. 安装MySQL 8.0：从MySQL官网下载MySQL 8.0的Installer。运行后，在“Choosing a Setup Type”页面，选择“Custom”以便精确控制。在添加新产品时，选择MySQL Server 8.0.x，并添加到右侧安装列表。执行安装。
4. 恢复数据：安装完成后，启动MySQL 8.0服务。然后使用命令行或工具导入之前备份的数据。

   mysql -u root -p < backup_all.sql

5. 重要配置调整：MySQL 8.0使用了新的默认身份验证插件caching_sha2_password，而一些旧的客户端或驱动（包括某些老版本的Django MySQL驱动）可能还不支持。这可能导致连接错误。如果遇到Authentication plugin 'caching_sha2_password' cannot be loaded这类错误，可以修改相应用户的身份验证方式（生产环境请谨慎评估安全影响）：

   ALTER USER 'your_username'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password'; FLUSH PRIVILEGES;

注意：在macOS上，如果同时存在多个MySQL版本（如通过brew link切换），务必确认环境变量PATH和任何启动脚本指向的是正确的8.0版本二进制文件。可以通过which mysql命令来检查。

3.2 升级后的Django项目配置检查

MySQL升级到8.0后，你的Django项目通常不需要修改代码，但需要检查一下settings.py中的数据库配置。

DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'your_database_name', 'USER': 'your_username', 'PASSWORD': 'your_password', 'HOST': 'localhost', # 或你的数据库地址 'PORT': '3306', # 默认端口 # MySQL 8.0 建议添加以下选项以确保连接稳定和字符集正确 'OPTIONS': { 'charset': 'utf8mb4', 'init_command': "SET sql_mode='STRICT_TRANS_TABLES'", # 如果使用mysqlclient驱动，且遇到认证问题，可以尝试指定旧的认证插件（不推荐长期使用） # 'init_command': "SET default_authentication_plugin='mysql_native_password'", } } }

关键点是'charset': 'utf8mb4'，这确保了Django和MySQL 8.0使用完整的UTF-8编码进行通信。STRICT_TRANS_TABLESSQL模式能让MySQL在执行数据写入时更严格，有助于提前发现数据问题。

升级完成后，再次运行python manage.py migrate，之前的NotSupportedError应该就会消失，项目可以正常启动。

4. 解决方案二：降级Django或适配驱动（兼容路径）

如果因为客观限制（如公司规定、老旧生产服务器、依赖的特定软件仅支持MySQL 5.7等），无法升级MySQL，那么我们就需要调整Django这一端，使其“兼容”MySQL 5.7。

4.1 降低Django框架版本

这是最直接的方法。Django 3.2是一个长期支持版本，其官方支持截止日期是2024年4月，它对MySQL的最低要求是5.6，完全兼容5.7。因此，将Django版本锁定在3.2.x系列，是一个相对安全的选择。

1. 修改项目依赖：在你的项目依赖管理文件（通常是requirements.txt或pyproject.toml）中，将Django版本固定。

   • requirements.txt示例：

     Django==3.2.25 # 指定3.2系列的最后一个版本，以获得最多的安全补丁 mysqlclient==2.2.4 # 兼容的MySQL驱动

   • 使用pip安装指定版本：

     pip install "Django==3.2.25"

2. 验证兼容性：降级后，务必全面测试你的项目功能。虽然Django 3.2和4.x在API上大部分兼容，但一些内部行为、默认设置或已废弃的警告可能会有所不同。重点测试与数据库交互复杂的部分，如使用JSONField、复杂查询、事务处理等。

实操心得：降级时，特别注意项目中使用到的第三方App（Django插件）。有些较新的App可能声明了依赖Django>=4.0，在降级后可能会无法安装或运行出错。你需要逐一检查并寻找这些App的兼容版本，或者寻找替代品。这往往是降级方案中最耗时的地方。

4.2 使用第三方数据库后端（不推荐用于生产）

社区中有一些第三方Django数据库后端，宣称提供了对旧版本MySQL的兼容。例如，曾经有django-mysql-backend这类项目。但是，我必须强烈警告你，这条路风险极高。

这些第三方后端通常是通过“欺骗”Django的版本检查，或者重新实现部分功能来绕过限制。它们可能无法完全实现Django ORM的所有特性，尤其是与特定MySQL版本强相关的功能（如JSONField在5.7上的部分功能）。更严重的是，它们可能无法及时跟进Django的安全更新，导致你的项目暴露在安全漏洞之下。

除非是极其临时的、本地的、无关紧要的调试用途，并且你完全清楚自己在做什么，否则绝对不要在生产环境或重要项目中使用第三方后端来规避版本检查。这无异于为了通过门卫检查而伪造证件，进去之后房子结构支不支持就是另一回事了。

4.3 调整PyMySQL或mysqlclient驱动（可能无效的尝试）

有些文章会建议，通过使用PyMySQL驱动并手动指定版本，或者修改mysqlclient的某些代码来“骗过”Django的版本检查。例如，在settings.py中这样配置：

import pymysql pymysql.version_info = (1, 4, 6, "final", 0) # 尝试伪造版本信息 pymysql.install_as_MySQLdb()

或者在代码中猴子补丁（monkey-patch）数据库检查逻辑。这些方法在Django 4.0及以后版本中基本都失效了，或者即使暂时绕过检查，也会在运行时引发更深层次的、难以调试的错误。Django的版本检查是在底层C扩展或核心连接逻辑中进行的，简单的驱动层伪装无法解决根本的兼容性问题。把时间花在这些“奇技淫巧”上，不如老老实实升级或降级。

5. 预防与排查：建立版本意识与问题定位

最好的解决方法是避免问题发生。建立清晰的版本管理意识，能让你在项目伊始就避开这类坑。

5.1 项目启动时的环境锁定

对于任何一个新项目，在requirements.txt或Pipfile中精确锁定所有核心依赖的版本，包括Django、数据库驱动（mysqlclient或pymysql）。同时，在项目文档（如README.md）中明确声明所需的数据库类型和版本。

# requirements.txt Django==4.2.11 mysqlclient==2.2.4

对于数据库，可以使用Docker来固化环境。一个docker-compose.yml文件能清晰地定义开发环境：

version: '3.8' services: db: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: rootpassword MYSQL_DATABASE: myproject MYSQL_USER: myuser MYSQL_PASSWORD: mypassword ports: - "3306:3306" volumes: - mysql_data:/var/lib/mysql web: build: . command: python manage.py runserver 0.0.0.0:8000 volumes: - .:/code ports: - "8000:8000" depends_on: - db volumes: mysql_data:

这样，任何克隆你项目的开发者，都能通过docker-compose up一键获得完全一致的环境，从根本上杜绝“在我机器上是好的”这类问题。

5.2 错误排查的完整链路

当你遇到类似“版本过低”的错误时，不要只看Django的错误信息，应该进行系统性的排查，以确认问题的全貌。

1. 确认Django版本：运行python -m django --version。
2. 确认MySQL实际运行版本：
   • 通过命令行连接：mysql -u root -p -e "SELECT VERSION();"
   • 在Django代码中临时打印（在settings.py加载后）：

     # 临时调试 import pymysql # 或 mysqlclient from django.db import connection with connection.cursor() as cursor: cursor.execute("SELECT VERSION()") db_version = cursor.fetchone() print(f"Connected MySQL version: {db_version[0]}")

3. 检查连接的是否是预期的MySQL实例：特别是在开发机上，可能安装了多个MySQL（比如系统自带、Homebrew安装、XAMPP/MAMP集成环境）。确认你的Django配置中的HOST和PORT指向的是正确的那个。使用mysql --host=127.0.0.1 --port=3306 -u root -p来测试连接。
4. 检查数据库驱动：mysqlclient和PyMySQL行为有细微差别。确保你安装的驱动与Django版本兼容。Django官方推荐mysqlclient。
5. 查看Django源码中的版本检查逻辑（进阶）：如果好奇，可以查看Django源码中django/db/backends/mysql/base.py文件，找到Database类下的check_database_version_supported方法，里面明确写着版本判断逻辑。这能帮你理解框架为何做出此要求。

5.3 常见连带问题与解决

升级或调整版本后，可能会遇到一些连带问题：

• 认证插件错误：如前所述，MySQL 8.0默认使用caching_sha2_password，旧驱动可能不支持。解决方案：要么升级驱动到最新版（mysqlclient2.1.0+ 已支持），要么修改MySQL用户认证方式（开发环境可临时使用，生产环境需评估）。
• 时区问题：Django和MySQL的时区设置不一致，可能导致存储和读取的DateTimeField有误差。确保在Django的settings.py中正确设置USE_TZ和TIME_ZONE，并在MySQL中设置统一的时区（例如SET GLOBAL time_zone = '+08:00';）。
• GROUP BY严格模式：MySQL 8.0默认启用了ONLY_FULL_GROUP_BYSQL模式，这比5.7更严格。某些在5.7下能运行的复杂查询可能在8.0下报错。你需要检查并重写这些查询，使其符合SQL标准，或者在Django的数据库配置OPTIONS中调整sql_mode（但这可能掩盖潜在的数据逻辑问题）。

6. 决策指南与长期维护建议

面对“版本过低”错误，如何选择解决方案？这里有一个简单的决策树供参考：

1. 环境是否可控？如果这是全新的个人项目、公司新项目，或者你有权限升级测试/生产数据库，那么毫不犹豫地选择升级MySQL到8.0+。这是面向未来的投资。
2. 项目是否复杂且依赖众多？如果是一个大型的、使用了大量最新Django特性（如异步、高级JSON查询）和第三方App的项目，降级Django的成本可能非常高（兼容性冲突）。此时，推动数据库升级是更可行的路径。
3. 是否是遗留维护项目？如果项目本身基于Django 2.2或3.2等旧版本，功能稳定，且生产数据库是MySQL 5.7且无法升级（如受制于基础设施），那么降级Django到对应的LTS版本（如3.2）是风险最小的选择。同时，应为项目制定一个中长期的升级计划。
4. 是否是临时调试或学习？如果只是为了快速运行一个别人的示例代码或进行一次性测试，可以考虑在本地使用Docker临时创建一个MySQL 8.0容器，与宿主机现有的5.7并存，互不干扰。这是最干净、最隔离的临时方案。

长期维护建议：将“依赖版本声明”作为项目最重要的文档之一。使用pyproject.toml（PEP 621）或requirements.in（配合pip-compile）来管理依赖，并区分开发依赖和生产依赖。在CI/CD流水线中，加入对数据库版本的检查步骤。定期（如每半年）评估一次核心依赖（Django, MySQL, Python）的版本，并计划升级。跟随主流支持的版本，能让你的项目更安全、更容易获得社区帮助。

我自己在维护多个项目时，会用一个简单的检查清单，在每次大版本升级前核对：

• [ ] 查阅Django发布说明，了解破坏性变更。
• [ ] 在独立的分支或容器中，用测试数据库进行升级演练。
• [ ] 运行完整的测试套件。
• [ ] 手动测试核心业务流。
• [ ] 检查所有第三方App的兼容性声明。
• [ ] 备份生产数据，并制定明确的、可回滚的升级方案。

数据库和框架的版本升级，就像是给行驶中的汽车更换更强大的引擎和底盘，过程需要谨慎，但结果是让整个系统跑得更稳、更快、更安全。那个NotSupportedError虽然看起来是个拦路虎，但何尝不是一次推动技术栈更新的契机呢？处理好它，你的项目就又在技术债的偿还路上前进了一步。