create-flask

_{一条命令，生成生产可用的现代 Flask 项目骨架}

---

create-flask 是一条命令生成 生产可用 Flask 项目骨架的 CLI：纯 Flask + Pydantic + SQLAlchemy 2.0，内置 uv / ruff / gunicorn 配置。

注意：工具只生成文件，不代跑 uv sync、数据库迁移或启动服务。首次使用请先完成 安装。

# 快速预览（需已安装 uv）
uv tool install git+https://github.com/xiongxianzhu/create-flask.git
create-flask my-api
cd my-api && uv sync && cp .env.example .env && uv run flask run  # Windows: copy .env.example .env

目录

• 技术栈
• 特性
• 安装
• 快速开始
• 命令参考
• 自定义模板
• 生成项目结构
• PyPI 镜像源
• llms.txt · AI 导航
• 开发

技术栈

create-flask 工具本身与生成项目使用不同技术栈，职责分离：

工具本身（create-flask CLI）

类别	技术
语言	Python 3.13
CLI	Typer
模板引擎	Jinja2
打包	hatchling
开发	uv · pytest · ruff · mypy

运行时依赖仅 Typer + Jinja2；模板渲染、可选模块门控、git 浅克隆均在此层完成。

生成项目（create-flask my-api 产物）

类别	技术
运行时	Python 3.13 · uv
Web	纯 Flask（蓝图 + 视图函数）
校验 / 配置	Pydantic · pydantic-settings
数据	SQLAlchemy 2.0 · Flask-SQLAlchemy · Flask-Migrate
代码质量	ruff · mypy
生产	gunicorn + supervisor + nginx

不依赖 Flask-RESTful / Flask-Smorest / Marshmallow。

可选模块（--redis / --celery / --docker，不计入核心栈）：

开关	技术
--redis	官方 redis 客户端
--celery	Celery（强制依赖 Redis）
--docker	Dockerfile · docker compose

特性

特性	说明
纯 Flask + Pydantic	蓝图 + 视图函数，入/出参用 Pydantic；不依赖 Flask-RESTful / Smorest / Marshmallow
现代工具链	uv 依赖管理 · ruff lint/format · mypy 类型检查 · pydantic-settings 配置
SQLAlchemy 2.0	Mapped / mapped_column 类型化模型 · Flask-Migrate 迁移
生产就绪	gunicorn + supervisor + nginx 模板 · 可选 Docker 容器化
可选模块	--redis（官方 redis 客户端）· --celery（强制依赖 Redis）· --docker
自定义模板	内置 / 本地目录 / git 仓库，同一套 Jinja 约定与模块门控

安装

要求：Python 3.13+；推荐 uv。使用 git 模板时需系统已安装 git。

推荐顺序：安装 uv → 安装 create-flask → 验证

安装 uv

create-flask 与生成项目均以 uv 管理依赖。若尚未安装，按平台执行：

Windows（PowerShell）

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 或：winget install --id=astral-sh.uv -e

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
# 或：brew install uv

通用（pip）

pipx install uv   # 推荐
# 或：pip install uv

验证安装：

uv --version
# 例如：uv 0.7.19

更多安装方式、升级与卸载见 uv 官方安装文档。

安装 create-flask

PyPI（发布后）

# 推荐：全局 CLI，任意目录可用
uv tool install create-flask

# 或 pip
pip install create-flask
pipx install create-flask

从 GitHub 安装（当前）

uv tool install git+https://github.com/xiongxianzhu/create-flask.git

# 更新或重装（上游有变更、安装失败或命中旧缓存时）
uv tool install --reinstall git+https://github.com/xiongxianzhu/create-flask.git

# 或 pip / pipx
pip install git+https://github.com/xiongxianzhu/create-flask.git
pipx install git+https://github.com/xiongxianzhu/create-flask.git

本地开发（贡献 / 调试）

git clone https://github.com/xiongxianzhu/create-flask.git
cd create-flask
uv sync

# 仓库内直接运行（无需全局安装）
uv run create-flask my-api

验证 create-flask

create-flask --version
# 例如：create-flask 0.1.0

create-flask --help

卸载

按安装方式对应卸载全局 CLI（不会删除已生成的项目目录）：

# uv tool 安装时
uv tool uninstall create-flask

# pip 安装时
pip uninstall create-flask

# pipx 安装时
pipx uninstall create-flask

本地开发（clone 仓库 + uv sync）无需卸载命令，删除 clone 目录即可。

快速开始

完成 安装 后，按下面步骤可在本地跑通一个 API 项目。

1. 生成项目

# 最简：默认模板
create-flask my-api

# 带可选模块
create-flask my-api --redis --celery --docker

# 其他常用参数
create-flask my-api --path ./services --force

# 仓库内开发（未全局安装 create-flask）
uv run create-flask my-api

2. 初始化并启动

进入生成目录，安装依赖、配置环境并启动：

cd my-api
uv sync
cp .env.example .env          # Windows: copy .env.example .env
# 按需修改 .env 中的 SECRET_KEY、DATABASE_URL 等

uv run flask db init
uv run flask db migrate -m "init"
uv run flask db upgrade
uv run flask run

启动后访问 http://127.0.0.1:5000，验证健康检查：

curl http://127.0.0.1:5000/health
# {"status":"ok"}

生成项目还提供 Makefile 快捷命令，等价于上述手动步骤：

make install    # uv sync
make env        # cp .env.example .env
make db-setup   # flask db init → migrate → upgrade
make run        # flask run

3. 可选模块（按需）

启用 --redis / --celery / --docker 时

Celery（需本地 Redis 可用）：

uv run celery -A wsgi:celery_app worker -l info
# 或：make celery

Docker：

docker compose up --build
# 或：make docker-up

容器内应用监听 0.0.0.0:8000，映射到宿主机 8000 端口。

更完整的开发、部署与代码质量说明见生成项目内的 README.md。

命令参考

create-flask <name> [OPTIONS]

参数	说明
<name>	项目名：小写，可用 - 分隔；不得含 _、空格或特殊字符
--path	目标目录，默认在当前目录创建 <name>/
--redis / --no-redis	集成 Redis 客户端（可选）
--celery	集成 Celery；自动启用 Redis，与 --no-redis 冲突时报错
--docker	生成 Dockerfile / docker-compose / .dockerignore
--template, -t	模板来源：内置（默认）/ 本地路径 / git 地址
--template-ref	git 模板的分支或标签
--template-subdir	模板根所在子目录
--force	覆盖已存在文件（默认跳过）
--yes, -y	跳过交互

自定义模板

-t 支持三种来源，渲染规则与内置模板一致（Jinja2 + 可选模块门控）：

# 内置（默认）
create-flask my-api

# 本地目录
create-flask my-api -t ./my-template

# git 仓库（浅克隆，结束后清理）
create-flask my-api -t https://github.com/user/flask-template
create-flask my-api -t git@github.com:user/repo.git \
  --template-ref main --template-subdir templates/api

外部模板约定

• 占位变量：{{ project_name }}、{{ package_name }}（- → _），及 use_redis / use_celery / use_docker；可用于文件内容与文件/目录名
• 点文件占位名：gitignore、dockerignore、python-version、env.example（生成时自动加点）
• 模块门控：celeryconfig.py、app/tasks/ 仅 --celery；Docker 三件套仅 --docker
• 路径示例：deploy/supervisor/{{ project_name }}.conf → deploy/supervisor/my-api.conf
• 其他：空目录用 .gitkeep；非文本文件原样复制；克隆的 .git/ 不进入产物

git 来源需系统已安装 git。http(s)://、git@、ssh://、git:// 或 .git 结尾按 git 处理，其余为本地路径。

生成项目结构

my-api/
├── app/
│   ├── core/          # 基类、异常、常量
│   ├── models/        # SQLAlchemy 2.0 模型
│   ├── schemas/       # Pydantic 入/出参
│   ├── services/      # 业务逻辑
│   ├── api/           # 蓝图 + 视图函数
│   ├── routes/        # 蓝图注册
│   ├── extensions.py  # db、migrate 等扩展实例
│   └── settings.py    # pydantic-settings
├── deploy/supervisor/ # 进程配置模板
├── tests/
├── wsgi.py
├── gunicorn.conf.py
├── Makefile           # 常用开发命令
└── pyproject.toml

PyPI 镜像源

本仓库与生成项目的 pyproject.toml 均默认使用腾讯 PyPI 镜像：

[tool.uv]
index-url = "https://mirrors.tencent.com/pypi/simple/"

若 uv sync 仍从其他镜像或官方 PyPI 拉包，常见原因如下。

优先级

uv 解析依赖时的镜像来源（高 → 低）：

1. 命令行 --index-url
2. 环境变量 UV_INDEX_URL
3. 项目 pyproject.toml 中的 [tool.uv] index-url
4. 官方 PyPI

因此 shell 里若设置了 UV_INDEX_URL（例如清华源），会覆盖项目内的腾讯源配置。uv 读取的是 UV_INDEX_URL，不是 PIP_INDEX_URL。

uv.lock 会固定下载地址

uv lock 会把当时使用的 registry 和包 URL 写入 uv.lock。仅修改 pyproject.toml 不会自动换源；需重新锁依赖：

# 若希望本项目严格走 pyproject.toml 中的腾讯源，可先取消全局覆盖
unset UV_INDEX_URL

uv lock
uv sync

推荐做法

场景	做法
仅本项目用腾讯源	不设 UV_INDEX_URL，保留 pyproject.toml 中的 index-url
所有项目统一镜像	在 ~/.zshrc 等设置 UV_INDEX_URL，与项目配置保持一致
切换镜像后	执行 uv lock 再 uv sync，并提交更新后的 uv.lock

llms.txt · AI 导航

仓库根目录的 llms.txt 遵循 llms.txt 规范，为 LLM / AI 助手提供精简索引——指向 README、PRD、核心源码与模板，避免通读全库。

文件	面向
llms.txt	LLM 快速定位文档与关键路径
AGENTS.md	Agent 协作约定、生成边界与开发命令

在 Cursor / Claude 等环境中，可将 llms.txt 作为上下文入口；Optional 小节内的链接可在上下文紧张时跳过。

开发

本仓库（create-flask CLI）常用命令：

uv sync
uv run pytest
uv run ruff check .
uv run mypy

---

_{MIT · 只生成文件，不代跑 uv sync / 迁移 / 启动}

_{姊妹项目 → create-fastapi}