• 文档说明

    本文档记录在 Ubuntu 系统中从 Python3.12 安装到 Flask 项目初始化的完整流程，包含核心操作步骤、常见问题解决方案及关键注意事项，适用于需要搭建隔离 Python 开发环境的场景。

    前置环境

    • 系统：Ubuntu（任意主流版本，本文基于 22.04 测试）
    • 权限：具备 sudo 权限（用于系统级软件安装）

    全流程操作步骤

    安装 Python3.12

    操作命令

    \# 更新系统包列表
sudo apt update && sudo apt install -y software-properties-common
\# 添加Python第三方源（deadsnakes，提供非默认Python版本）
sudo add-apt-repository -y ppa:deadsnakes/ppa
\# 安装Python3.12及核心依赖
sudo apt install -y python3.12 python3.12-dev python3.12-venv
\# 验证安装
python3.12 --version

    终端输出 Python 3.12.x（x 为具体版本号），代表安装成功。

    配置 Python3 默认版本

    系统默认python3可能指向 Python3.10，需通过update-alternatives切换到 3.12。

    \# 为Python3.10和3.12创建版本管理入口
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 100
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 110
\# 选择默认版本（输入Python3.12对应的序号）
sudo update-alternatives --config python3
\# 验证
python3 --version
    • 部分系统工具（如apt）依赖 Python3.10，若切换后出现系统报错，可重新执行sudo update-alternatives --config python3切换回 3.10。

    安装并配置 pipx

    \# 安装系统pip（若未自带）
sudo apt install -y python3-pip
\# 安装pipx（用户级安装，避免系统环境污染）
python3 -m pip install --user pipx
\# 配置pipx环境变量（确保终端识别pipx命令）
python3 -m pipx ensurepath
    • 执行完上述命令后，必须重启终端（或执行source ~/.bashrc）使环境变量生效。

    验证命令

    pipx --version

    • 问题：执行python3 -m pip install --user pipx时报ModuleNotFoundError: No module named 'distutils'

    • 解决：安装 Python3.12 的 distutils 依赖

    \# 方案1：直接安装依赖（优先）
sudo apt update && sudo apt install -y python3.12-distutils
\# 方案2：若方案1失败，用Python3.12自带工具补装
python3.12 -m ensurepip --upgrade
\# 重新安装pipx
python3.12 -m pip install --user pipx

    用 pipx 安装 Poetry

    \# 隔离安装Poetry（避免依赖冲突）
pipx install poetry
\# 验证
poetry --version

    终端输出Poetry (version x.x.x)，代表安装成功。

    • 若提示 “找不到 pipx 命令”，重启终端或执行source ~/.bashrc刷新环境变量。

    用 Poetry 创建并管理 Flask 项目环境

    初始化项目

    \# 新建项目目录并进入
mkdir poetry-project && cd poetry-project/demo
\# 初始化Poetry项目（按提示操作，回车用默认值）
poetry init
\# 安装项目依赖（跳过项目打包，避免报错）
poetry install --no-root

    虚拟环境激活与管理

    \# 查看当前项目环境
poetry env list
\# 激活环境（项目目录下直接执行，无需加环境名）
poetry env activate

    • 激活成功标志：终端提示符前出现(项目名-环境标识-py3.12)

    • 若习惯用poetry shell命令，可安装插件：

    poetry self add poetry-plugin-shell
poetry shell  # 安装后即可使用

    退出环境

    deactivate

    安装 Flask 并初始化项目

    \# 安装Flask到虚拟环境
poetry add flask
\# 用虚拟环境执行Flask初始化命令（核心：加poetry run）
poetry run flask init

    常用命令清单

    环境验证命令

    \# 验证Python版本
python3 --version && python3.12 --version
\# 验证pipx和Poetry
pipx --version && poetry --version
\# 验证虚拟环境
poetry env list && python --version  # 激活环境后执行

    项目操作命令

    \# 安装依赖
poetry add 包名  # 单个包
poetry install   # 从lock文件安装所有依赖
\# 执行项目命令
poetry run 命令   # 如：poetry run python app.py
\# 查看依赖
poetry show

    注意事项

    1. 避免用 root 用户操作：root 用户安装可能导致权限问题，建议切换普通用户（su 用户名）。

    2. poetry run的必要性：即使激活环境，部分终端仍需用poetry run确保命令在虚拟环境中执行。

    3. 永久解决poetry install报错：修改pyproject.toml，添加package-mode = false