Python 多版本治理理念（Windows 平台 · 零基础友好）-CSDN博客

Python 多版本与开发环境治理架构设计-CSDN博客

使用命令行创建项目本地的 Poetry 虚拟环境实战演示 —— 基于《Python 多版本与开发环境治理架构设计》的最佳实践-CSDN博客

一、Python311 环境工具链准备

1. 环境结构与工具路径

python311 环境（Python 3.11）
├─ python.exe: D:\ProgramData\anaconda3\envs\python311\python.exe
├─ 工具路径: D:\ProgramData\anaconda3\envs\python311\Scripts\
│  ├─ poetry.exe: 依赖管理工具
│  ├─ virtualenv.exe: 虚拟环境创建工具
│  ├─ pipenv.exe: 另一种依赖管理工具
│  ├─ uv.exe: 轻量级虚拟环境工具
│  └─ hatch.exe: Python项目管理工具
├─ PyCharm解释器路径: 同上
└─ 终端命令示例:├─ poetry: "D:\...\poetry.exe" init├─ virtualenv: "D:\...\python.exe" -m virtualenv .venv└─ 其他工具调用方式类似

2. 工具链路径准备

│  │  
│  ├─ python311 环境（Python 3.11）  
│  │  ├─ python.exe: D:\ProgramData\anaconda3\envs\python311\python.exe  
│  │  ├─ 工具路径: D:\ProgramData\anaconda3\envs\python311\Scripts\  
│  │  │  ├─ poetry.exe: D:\ProgramData\anaconda3\envs\python311\Scripts\poetry.exe

二、Poetry 虚拟环境创建五步流程

# 1、交互式生成项目配置文件pyproject.toml
"D:\ProgramData\anaconda3\envs\python311\Scripts\poetry.exe" init# 2、强制使用Conda环境中的Python 3.11创建虚拟环境
poetry env use "D:\ProgramData\anaconda3\envs\python311\python.exe"# 3、激活Windows系统下的本地虚拟环境
.venv\Scripts\activate# 4、在虚拟环境中安装Poetry，实现工具链本地化
pip install poetry# 5、在虚拟环境中验证工具链的本地化
python -V
where python
poetry -V
where poetry

步骤详解：

1. 初始化 Poetry 项目

"D:\ProgramData\anaconda3\envs\python311\Scripts\poetry.exe" init  # 显式调用Conda环境的Poetry

F:\PythonProjects\suna>"D:\ProgramData\anaconda3\envs\python311\Scripts\poetry.exe" init

This command will guide you through creating your pyproject.toml config.

Package name [suna]:    #输入项目名称或按回车键使用默认名称[suna]
Version [0.1.0]:    #输入项目版本号或按回车键使用默认版本[0.1.0]
Description []: AI Agent SUNA #输入项目描述信息或按回车键跳过输入
Author [****** <******@qq.com>, n to skip]: 按回车键 #按回车键确认自动关联的作者信息或输入 n 跳过
License []: MIT   #输入项目许可证类型或按回车键跳过输入
Compatible Python versions [>=3.8]: ^3.11   #修改支持的python版本或按回车键跳过输入（当前默认 >=3.8 ，我输入^3.11修改为支持3.11版本）

Would you like to define your main dependencies interactively? (yes/no) [yes] NO #输入项目的主要依赖项信息或按回车键跳过输入
Would you like to define your development dependencies interactively? (yes/no) [yes] NO #输入项目的开发依赖项信息或按回车键跳过输入
Generated file

[project]
name = "suna"
version = "0.1.0"
description = "AI Agent SUNA"
authors = [
{name = "******",email = "******@qq.com"}
]
license = {text = "MIT"}
readme = "README.md"
requires-python = "^3.11"
dependencies = [
]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

Do you confirm generation? (yes/no) [yes] YES #你确认生成吗？输入 YES 确认

建议：除非必须交互输入的外，创建 poetry 时，能不配置的先不配置（避免因配置错误而创建环境受阻），也就是输入NO 然后回车或直接回车使用默认配置。

生成的核心配置文件：

pyproject.toml 内容参考：

[project]
name = "suna"
version = "0.1.0"
description = "AI Agent SUNA"
authors = [{name = "******",email = "******@qq.com"}
]
license = {text = "MIT"}
readme = "README.md"
requires-python = "^3.11"
dependencies = [
][build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

2. 配置本地虚拟环境生成路径（可选）

Poetry 有时会默认将虚拟环境创建在系统的缓存目录下，而不是项目目录中。

# 配置Poetry在项目目录内创建虚拟环境
poetry config virtualenvs.in-project true

3. 强制指定 Python 解释器创建环境

# 使用Conda环境中的Python 3.11创建虚拟环境
poetry env use "D:\ProgramData\anaconda3\envs\python311\python.exe"# 关键输出:
# Creating virtualenv suna in F:\PythonProjects\suna\.venv

4. 激活本地虚拟环境

# Windows系统下激活虚拟环境
.venv\Scripts\activate# 状态确认:
# 命令行前缀变为 (suna-py3.11) (python311)

5. 工具链本地化（推荐步骤）

# 在虚拟环境中安装Poetry，实现工具链隔离
pip install poetry

三、环境独立性验证

1. 路径验证（激活后）

# 检查Python路径（首位为本地.venv）
where python  
# 输出: F:\PythonProjects\suna\.venv\Scripts\python.exe# 检查Poetry路径（新增本地路径）
where poetry  
# 输出: F:\PythonProjects\suna\.venv\Scripts\poetry.exe

2. 脱离 Conda 环境验证

# 退出所有环境后重新激活
exit          # 退出Poetry虚拟环境
conda deactivate  # 退出Conda环境
.venv\Scripts\activate      # 仅通过本地.venv激活Poetry环境# 最终验证:
python -V  # 仍显示 Python 3.11.11
where python   # 本地.venv 路径内的 python 显示在首位
where poetry  # 本地.venv 路径内的 poetry 显示在首位

四、技术原理与治理价值

工具链借用模式：
通过 Conda 环境的 Poetry 工具链初始化项目，仅作为 “构建工具”，避免直接依赖 Conda 环境开发。
三级隔离体系：
- 工具链层：Conda 提供基础工具
- 环境层：Poetry 在项目目录生成.venv
- 应用层：依赖与代码封装在.venv 中
工程化价值：
- 环境自包含：.venv 可随项目迁移，通过poetry install重建
- 版本可控：pyproject.toml明确 Python 版本边界，避免依赖冲突