环境搭建：Python 虚拟环境管理、pip install flask 与首个 App

📂 所属阶段：第一阶段 — 破冰启航（基础篇）
🔗 相关章节：初识 Flask · 路由（Routing）艺术

1. 为什么需要虚拟环境？

1.1 虚拟环境解决的问题

项目A需要 Flask 2.0      项目B需要 Flask 3.0
         ↓                      ↓
    全局安装 Flask 2.0    全局安装 Flask 3.0？
         ↓                      ↓
     冲突！版本打架 😱        只能选一个？

虚拟环境：每个项目独立的环境，互不干扰 ✅

1.2 venv 内置模块

Python 3.3+ 自带 venv，无需额外安装。

# 创建虚拟环境
python -m venv venv

# 激活
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# Windows CMD:
venv\Scripts\activate.bat
# macOS / Linux:
source venv/bin/activate

# 激活后命令提示符前会显示 (venv)
(venv) PS D:\code2026\project>

2. 安装 Flask 及依赖

2.1 基础安装

pip install flask

2.2 项目依赖管理

# 安装 Flask 及常用扩展
pip install flask flask-sqlalchemy flask-login flask-wtf flask-migrate flask-cors

# 安装完成后，冻结依赖清单
pip freeze > requirements.txt

2.3 requirements.txt

Flask>=3.0.0
Flask-SQLAlchemy>=3.1.0
Flask-Login>=0.6.3
Flask-WTF>=1.2.0
Flask-Migrate>=4.0.0
Flask-CORS>=4.0.0
email-validator>=2.0.0
python-dotenv>=1.0.0

2.4 恢复依赖

# 在新机器上安装所有依赖
pip install -r requirements.txt

3. 项目初始化

3.1 创建项目目录

mkdir daoman_blog
cd daoman_blog
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install flask

3.2 Flask 项目标准目录结构

daoman_blog/
├── app/                       # 应用包
│   ├── __init__.py           # 应用工厂 create_app()
│   ├── routes/                # 路由模块（蓝图）
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── auth.py
│   │   └── articles.py
│   ├── models/               # 数据模型
│   │   ├── __init__.py
│   │   └── user.py
│   ├── templates/            # Jinja2 模板
│   │   ├── base.html
│   │   ├── index.html
│   │   └── auth/
│   │       └── login.html
│   ├── static/               # 静态资源
│   │   ├── css/
│   │   ├── js/
│   │   └── uploads/
│   └── extensions.py         # 扩展初始化
├── migrations/               # Alembic 数据库迁移
├── tests/                    # 测试代码
├── .env                      # 环境变量（不上传 Git）
├── .env.example              # 环境变量模板
├── requirements.txt          # 依赖清单
├── config.py                 # 配置文件
└── run.py                    # 启动脚本

4. 应用工厂模式

4.1 扩展初始化（extensions.py）

# app/extensions.py
from flask_sqlalchemy import SQLAlchemy
from flask_login import LoginManager
from flask_migrate import Migrate
from flask_wtf.csrf import CSRFProtect

db = SQLAlchemy()
login_manager = LoginManager()
migrate = Migrate()
csrf = CSRFProtect()

login_manager.login_view = "auth.login"  # 未登录重定向到登录页
login_manager.login_message = "请先登录后再访问。"

4.2 应用工厂（init.py）

# app/__init__.py
from flask import Flask
from config import config
from app.extensions import db, login_manager, migrate, csrf

def create_app(config_name="development"):
    app = Flask(__name__)
    app.config.from_object(config[config_name])

    # 初始化扩展
    db.init_app(app)
    login_manager.init_app(app)
    migrate.init_app(app, db)
    csrf.init_app(app)

    # 注册蓝图
    from app.routes.main import main_bp
    from app.routes.auth import auth_bp
    app.register_blueprint(main_bp)
    app.register_blueprint(auth_bp, url_prefix="/auth")

    return app

4.3 配置文件（config.py）

# config.py
import os
from dotenv import load_dotenv

load_dotenv()  # 加载 .env 文件

class Config:
    SECRET_KEY = os.getenv("SECRET_KEY", "dev-key-change-me")
    SQLALCHEMY_DATABASE_URI = os.getenv(
        "DATABASE_URL", "sqlite:///daoman.db"
    )
    SQLALCHEMY_TRACK_MODIFICATIONS = False

class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///daoman_dev.db"

class ProductionConfig(Config):
    DEBUG = False

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"

config = {
    "development": DevelopmentConfig,
    "production": ProductionConfig,
    "testing": TestingConfig,
    "default": DevelopmentConfig,
}

4.4 启动脚本（run.py）

# run.py
import os
from app import create_app

config_name = os.getenv("FLASK_ENV", "development")
app = create_app(config_name)

if __name__ == "__main__":
    app.run(
        host="127.0.0.1",
        port=5000,
        debug=True,
    )

5. 使用 .env 管理环境变量

5.1 安装 python-dotenv

pip install python-dotenv

5.2 创建 .env 和 .env.example

# .env（实际值，不上传 Git）
SECRET_KEY=your-super-secret-key-here
DATABASE_URL=sqlite:///daoman.db
FLASK_ENV=development
MAIL_SERVER=smtp.example.com
MAIL_USERNAME=your@email.com
MAIL_PASSWORD=your-email-password
# .env.example（模板，上传 Git，给协作者参考）
SECRET_KEY=change-this-to-a-random-secret
DATABASE_URL=sqlite:///daoman.db
FLASK_ENV=development

5.3 .gitignore

# .gitignore
.env
__pycache__/
*.pyc
*.db
venv/
.venv/
static/uploads/
.coverage
htmlcov/

6. 数据库初始化

6.1 Flask-SQLAlchemy 数据库创建

# 进入 Python shell
flask shell

>>> from app import create_app
>>> from app.extensions import db
>>> app = create_app()
>>> with app.app_context():
...     db.create_all()
...     print("数据库表创建成功！")

6.2 Flask-Migrate 迁移管理

# 初始化迁移
flask db init

# 创建迁移
flask db migrate -m "add user table"

# 应用迁移
flask db upgrade

# 回滚
flask db downgrade

7. 小结

Flask 项目初始化清单：

1. python -m venv venv          创建虚拟环境
2. pip install flask ...        安装依赖
3. pip freeze > requirements.txt 导出依赖
4. 创建目录结构                  app/ static/ templates/ tests/
5. 创建 .env + .env.example    环境变量
6. 创建 .gitignore             忽略敏感文件
7. flask db init                初始化迁移
8. python run.py                启动开发服务器

💡 最佳实践：从第一天起就使用应用工厂模式和虚拟环境。虽然最小应用可以直接写在一个文件里，但养成规范习惯能避免以后重构的痛苦。

🔗 扩展阅读