flask: flask db 报错：Multiple heads are present; please specify a single target revision

一，报错：

ERROR [flask_migrate] Error: Multiple heads are present; please specify a single target revision

完整的报错信息：

$ flask db stamp head
/data/python/flask/panda-sys/venv/lib/python3.10/site-packages/pymilvus/client/__init__.py:6: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  from pkg_resources import DistributionNotFound, get_distribution
INFO  [sqlalchemy.engine.Engine] SELECT DATABASE()
INFO  [sqlalchemy.engine.Engine] [raw sql] {}
INFO  [sqlalchemy.engine.Engine] SELECT @@sql_mode
INFO  [sqlalchemy.engine.Engine] [raw sql] {}
INFO  [sqlalchemy.engine.Engine] SELECT @@lower_case_table_names
INFO  [sqlalchemy.engine.Engine] [raw sql] {}
INFO  [alembic.runtime.migration] Context impl MySQLImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [sqlalchemy.engine.Engine] BEGIN (implicit)
INFO  [sqlalchemy.engine.Engine] DESCRIBE `xmshopy_dev`.`alembic_version`
INFO  [sqlalchemy.engine.Engine] [raw sql] {}
INFO  [sqlalchemy.engine.Engine] SELECT alembic_version.version_num 
FROM alembic_version
INFO  [sqlalchemy.engine.Engine] [generated in 0.00024s] {}
INFO  [sqlalchemy.engine.Engine] ROLLBACK
ERROR [flask_migrate] Error: Multiple heads are present; please specify a single target revision

二，原因：

核心原因：你的迁移历史中出现了分叉（有多个 head 版本）。当你运行 flask db upgrade 或 flask db migrate 时，Alembic 不知道应该沿着哪条线继续往下走。

这通常是因为团队多人协作时，大家在各自的本地同时生成了迁移脚本，导致有多个文件的 down_revision 指向了同一个父版本。

三，解决 ：

执行命令：

 flask db merge heads -m "merge multiple heads"

例子：

$ flask db merge heads -m "merge multiple heads"
/data/python/flask/panda-sys/venv/lib/python3.10/site-packages/pymilvus/client/__init__.py:6: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  from pkg_resources import DistributionNotFound, get_distribution
  Generating /data/python/flask/panda-sys/migrations/versions/08125ca48cfc_merge_multiple_heads.py ...  done