1. 先说清楚EPGF 项目的“自包含”到底是什么1.1 为什么“工具本地化”是必做环节新手玩 EPGF 这类框架项目时最容易遇到的一个问题不是代码写不出来而是环境先崩了。今天在这台机器上跑得好好的明天换个电脑或者同事拉一下代码一堆依赖报错、Python 版本不一致、Poetry 全局环境互相污染。排查一圈才发现问题全部出在“工具装在了全局”这件事上。所谓“工具本地化”说白了就是把 Python 虚拟环境和 Poetry 的项目级配置全部收敛到项目文件夹内部。项目根目录下生成一个.venv文件夹里面单独放一套干净的解释器和依赖项目的 pyproject.toml、poetry.lock 把依赖版本全部锁死。这样项目本身就是一个自洽的“孤岛”不管放到哪台机器只要安装了基础运行时一条poetry install就能把环境完整还原。在做 EPGF 项目的日常开发时我把这套流程当成默认规范来执行。原因很简单EPGF 这类基础设施级项目依赖项多、版本敏感任何一个包浮动版本都可能引发连锁问题。与其让环境问题反复干扰业务开发不如从一开始就用 Poetry 把依赖管起来并在项目内部完成工具链隔离。这就是标题里说的“工具本地化为必做环节”——它不是加分项而是避免后期返工的前提。1.2 这套方案解决的核心痛点我见过很多新手的真实状态开发一个项目Python 用的是全局解释器装包用 pip今天装一个 requests明天卸一个 numpy偶尔遇到版本冲突干脆pip install --upgrade强制升级。短期看确实“能跑”但等到项目变大你会发现几个很头疼的问题全局环境越来越乱你根本不知道某个包是被哪个项目依赖的也不敢随便卸载。不同项目往往需要同一个包的不同版本全局环境只能装一个来回切换等于自找麻烦。代码提交到 Git 后别人拉下来依赖装不全缺哪个包全靠 README 手工说明。有一天你重装系统或者换电脑想恢复开发环境等于从头再装一遍费时费力还要碰运气。项目自包含 工具本地化这套组合拳正好把上面这些痛点全部按住。Python 解释器不依赖系统级而是项目级依赖不靠requirements.txt简单罗列而是通过 Poetry 在 pyproject.toml 里结构化声明并生成 poetry.lock 锁定精确版本虚拟环境路径统一放到.venv里让 PyCharm 自动识别。任何一个开发成员拿到项目只需要执行poetry install几秒钟到几分钟环境就齐了。这也是我坚持在 EPGF 项目中推行 Poetry 的原因。它的依赖解析速度、分组管理能力、发布集成程度都比裸 pip 好太多。更关键的是Poetry 原生支持“项目内创建虚拟环境”的配置这正好满足我们的本地化要求。2. 环境准备把 Python 和 Poetry 装成“稳定的底座”2.1 Python 安装版本选择与 PATH 问题在讲 PyCharm 和 Poetry 之前必须先把 Python 装明白。很多新手栽在第一步不是装不上而是装完不知道装到哪去了。先强调一个原则不要装预览版老老实实选稳定版。EPGF 项目在开发中一般建议使用 Python 3.10 或 3.11 这类经过大量工具链适配的版本。太老版本可能缺少新语法支持太新版本有些第三方库还没跟上会出现编译报错。以我自己为例主力环境用的是 Python 3.11跑 EPGF 相关的框架和插件完全没有兼容问题。下载安装包时到官方网站下载 Windows installer注意看版本号那串数字比如“3.11.9”后面还有没带 32-bit 还是 64-bit现在基本统一选 64-bit。安装过程中的关键点第一步安装界面的最下方有一个Add Python to PATH复选框一定要勾上。如果不勾后面在命令行里输入python会提示找不到命令到时候再来配环境变量虽然也能补救但没必要绕弯子。安装完成后验证方式很简单打开命令行工具输入python --version如果输出了类似Python 3.11.9的信息说明 Python 已经正常进入系统变量。此时顺手验证一下 pippip --version这两个命令都正常输出说明 Python 的基础链路已经通了。值得一提的是如果你在命令行里执行python后进入的是 Microsoft Store 的应用商店而不是 Python 解释器说明 PATH 顺序有问题或者环境变量被商店应用劫持了这时候去“设置 - 应用 - 高级应用设置 - 应用执行别名”里把两个python.exe的别名关掉就能恢复正常。2.2 Poetry 安装的三种姿势我推荐哪一种Poetry 的安装方式不少我见过的主要有三种官方安装脚本、pipx 隔离安装、直接用 pip 安装。我分别说下利弊。第一种官方 PowerShell 安装脚本(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -这是官方推荐的方式。脚本会把 Poetry 安装到用户目录下的%USERPROFILE%\.local\binWindows 环境不污染全局 Python 环境升级也方便。第二种pipx 安装pipx install poetrypipx 本身就是用来隔离安装 Python 命令行工具的用它装的 Poetry 很干净每个工具都在独立环境里运行。但前提是机器里已经装好了 pipx等于多一步前置操作。第三种直接用 pippip install poetry这种方式最省事也是新手最容易成功的路径。缺点是有可能被全局环境的包冲突影响到。不过对于刚开始学 EPGF 教程的同学我倒是认为可以先直接用 pip 装把主要精力放到项目环境搭建上等玩熟了再换成隔离安装在日常工作中也用得上。装完之后还是老规矩验证一下poetry --version如果提示poetry-poetry之类的错误或者直接提示“不是内部或外部命令”多半是 PATH 没生效。此时重新打开一个命令行窗口再执行一次。如果还是不行检查用户环境变量里有没有把%USERPROFILE%\.local\bin加进去。2.3 让 Poetry 走国内镜像装快不糟心这一步是纯经验补充。默认情况下Poetry 走的官方软件源在国外国内网络环境下创建项目或者添加依赖时经常遇到下载慢、超时、重试失败的情况。解决方法很简单给 Poetry 配置一个国内镜像源。我用的方式在 pyproject.toml 里显式声明[[tool.poetry.source]] name aliyun url https://mirrors.aliyun.com/pypi/simple/ priority primary如果你更习惯用 API 方式也可以一句话配完poetry source add --priorityprimary aliyun https://mirrors.aliyun.com/pypi/simple/配置之后依赖下载速度会明显提升。这里有个细节在 Poetry 2.x 版本里priority primary代表这个源是主源一旦设置了主源PyPI 默认源就会被忽略。如果你需要回退到官方源改成priority default或者直接删掉这个 source 块即可。这一步对新手来说非常实用。我第一次用 Poetry 给 EPGF 项目装依赖时没配镜像一个 Pillow 装了十分钟还没结束最后卡在编译依赖上直接报错。配置完国内源之后整个项目依赖安装时间压缩到两分钟以内体验完全不一样。3. 在 PyCharm 中文版 GUI 中创建 Poetry 项目3.1 先确认 PyCharm 的 Poetry 插件现在很多新手用的 PyCharm 已经带中文语言包了界面路径和英文版略有差异但底层逻辑一样。打开 PyCharm 后先看左侧的“项目”右上角齿轮旁边的“设置”进入“插件”市场搜索 Poetry确认插件已经安装并且处于启用状态。这里有个容易忽略的点PyCharm 的社区版和 Professional 专业版对新项目里的 Poetry 支持程度不同。社区版需要在创建项目后手动配置 Poetry 环境和解释器而专业版可以直接在“新建项目”向导里选择 Poetry。EPGF 教程里的项目一般规模不大社区版完全够用只是操作步骤多一步后面我会把两条路径都写清楚。3.2 GUI 创建流程专业版直接走 New Project 向导如果你的 PyCharm 是专业版创建 Poetry 项目非常简单。打开“文件”菜单选择“新建项目”在弹出的窗口左侧选择“Poetry”。关键字段有三个“位置”项目文件夹路径建议新建一个空目录避免路径里出现中文或空格。“Python 解释器”选择你本机已经装好的 Python 版本Poetry 会用这个版本来创建虚拟环境不需要手动指定.venv后面再改。“Poetry 可执行文件”这里默认会自动识别你安装的 Poetry 路径如果识别不到手动点击文件夹图标定位到poetry.exe所在位置。设置完成之后点击“创建”PyCharm 会自动做三件事在当前目录生成基础项目结构、调用 Poetry 创建虚拟环境、自动激活环境并安装基础依赖。整个过程都是图形化展示的底部可以看到进度条和日志输出。创建完成后看右下角或者右下侧的解释器状态栏如果显示的是“Python 3.11 (.venv)”说明项目已经处于 Poetry 管理的虚拟环境中。此时打开终端面板命令行前会自动带上(.venv)前缀表示当前 shell 已经激活了项目虚拟环境。3.3 命令行创建 PyCharm 导入路线社区版看这里社区版用户没有“Poetry 新建项目”选项卡但完全可以用命令行创建项目再用 PyCharm 打开。这条路线我认为更通用因为不管团队里别人用什么编辑器命令行流程是稳定一致的。先找一个合适的目录执行poetry new epgf-project这条命令会生成一个标准的 Poetry 项目结构epgf-project/ ├── epgf_project/ │ └── __init__.py ├── tests/ │ └── __init__.py ├── pyproject.toml └── README.md进入项目目录后创建虚拟环境cd epgf-project poetry env use python3.11这里的python3.11也可以替换成你机器上具体的 Python 版本或者直接使用python指向系统 PATH 里的默认版本。执行成功后可以在终端确认poetry env info输出里会看到Virtualenv的路径。如果这时候路径显示的是项目根目录下的.venv说明配置已经生效如果不是别急下一章专门讲这个。然后打开 PyCharm选择“打开”并定位到这个项目目录。第一次打开时PyCharm 可能会提示配置解释器我们选择“设置 - 项目 - Python 解释器”点击齿轮图标“添加解释器”选择“现有环境”在 Poetry 虚拟环境路径中定位.venv\Scripts\python.exe。配置完成后写一行代码测试链路import sys print(sys.executable)运行这段代码如果输出的路径里包含.venv说明整个 GUI 配置流程已经串起来了。4. 把 Poetry 做成项目自包含核心配置和文件解读4.1 关键配置让虚拟环境锁定在项目内这里直接给结论Poetry 默认的虚拟环境不一定在项目内部。如果你的电脑里配了缓存目录它可能会把虚拟环境放在用户目录下的AppData\Local\pypoetry\Cache\virtualenvs或者类似位置。这对单机开发影响不大但一旦项目复制、分享、换机这套虚拟环境就跟丢了重新配置还得花时间。我们要做的就是让 Poetry 把.venv直接放到项目目录下。打开 PyCharm 集成的终端执行poetry config virtualenvs.in-project true设置完这一行之后以后每次为这个项目创建虚拟环境Poetry 都会把环境放在项目根目录的.venv文件夹内。你可以用poetry config --list确认配置输出有没有virtualenvs.in-project true。如果你希望多个项目共享同一个虚拟环境缓存目录可以手动指定路径poetry config virtualenvs.path D:\Python\PoetryEnvs但我个人强烈不建议这么干。原因还是那个“本地化”原则项目如果依赖外部路径就有被外部变更波及的风险。老老实实把.venv放进项目文件夹能打包、能随项目走这才是真正的自包含。4.2 pyproject.toml 和 poetry.lock 分别承担什么角色Poetry 项目里有两个文件是核心中的核心pyproject.toml和poetry.lock。pyproject.toml是项目依赖的“声明文件”。它的结构类似这样[tool.poetry] name epgf-project version 0.1.0 description EPGF project toolchain authors [Your Name youexample.com] [tool.poetry.dependencies] python ^3.11 requests ^2.32.0 flask ^3.0.0 [tool.poetry.group.dev.dependencies] pytest ^8.0.0 ruff ^0.4.0 [build-system] requires [poetry-core] build-backend poetry.core.masonry.api依赖声明分为两块主依赖[tool.poetry.dependencies]和开发依赖[tool.poetry.group.dev.dependencies]。主依赖是运行时必须的比如 Flask、requests开发依赖是可选的比如 pytest、ruff只在开发测试时用到。这样做的好处是部署环境可以用poetry install --without dev只装必要依赖不额外拖入测试工具链。poetry.lock则是由 Poetry 自动生成并维护的“锁定文件”。它记录了每个依赖的精确版本、传递依赖、哈希值、来源信息等。只要提交上去团队所有成员执行poetry install时安装的版本完全一致连依赖的依赖都一样不存在“我这边能跑你那边报错”的魔幻问题。这两份文件一个是“我要什么”一个是“实际装了什么”配合起来就是可复现环境的基础。4.3 常用命令操作梳理日常开发足够的命令清单Poetry 的命令体系并不复杂日常开发真正高频使用的就几个。poetry add用于添加一个新的依赖。比如要给 EPGF 项目加入一个解析 Excel 的库poetry add openpyxl添加开发环境专用的依赖poetry add --group dev pytest安装项目的所有依赖poetry install如果只想装主依赖不装开发依赖poetry install --without dev移除一个依赖poetry remove openpyxl更新依赖版本poetry update查看当前环境的依赖树poetry show --tree进入 Poetry 的虚拟环境 shellpoetry shell在虚拟环境中执行一条命令但不进入交互式 shellpoetry run python your_script.py每一次poetry add或者poetry removePoetry 都会自动更新pyproject.toml和poetry.lock不需要手工去改文件这也是比 pip 更省心的一个点。日常开发时我习惯用poetry run配合 PyCharm 终端操作这样可以时刻保持对当前环境的清晰感知避免误操作到全局环境。5. 常见问题与排查实录5.1 几个新手最容易踩的坑下面这些坑都是我实际带新人时反复遇到的问题列成速查表方便自查。问题现象为什么会发生解决办法命令行输入poetry提示“不是内部或外部命令”Poetry 安装后 PATH 未生效或安装目录不在 PATH 中重新打开命令行检查用户环境变量中的%USERPROFILE%\.local\bin必要时手动添加PyCharm 终端激活虚拟环境后Python 版本还是全局版解释器未正确指向.venv在“设置 - 项目 - Python 解释器”里点击“添加解释器 - 现有环境”选择.venv\Scripts\python.exepoetry install下载速度极慢或超时未配置国内镜像源在 pyproject.toml 里增加 aliyun 源或使用poetry source add指令创建项目后找不到.venvvirtualenvs.in-project未设置或旧环境还在缓存路径下执行poetry config virtualenvs.in-project true然后重新poetry env remove并重建环境执行poetry add时提示 Python 版本不满足要求项目声明的python版本约束和新包冲突或当前解释器版本过低检查pyproject.toml中python ^3.11声明确认poetry env use指向正确版本运行程序时报ModuleNotFoundError依赖没安装全或装到了错误环境先确认终端有没有(.venv)前缀再执行poetry install --with devPowerShell 执行安装脚本时报执行策略错误系统默认禁止运行脚本以管理员身份执行Set-ExecutionPolicy RemoteSigned然后再跑安装脚本这里重点提醒一下“执行策略错误”。Windows 的 PowerShell 默认对脚本执行限制比较严格很多新手在安装 Poetry 的第一步就卡住了。看到红色报错不要慌这不是 Poetry 的问题是系统的安全策略。管理员权限的 PowerShell 里执行一次性授权Set-ExecutionPolicy RemoteSigned -Scope CurrentUser之后再次运行官方安装脚本即可。还有一个细节poetry 虚拟环境激活后Windows 终端会显示(.venv)但它其实是一条软链接类型的路径不要在资源管理器里把.venv文件夹移动到别的地方移动之后虚拟环境会失效。正确做法是如果需要移动项目位置直接复制整个项目文件夹然后在新的位置重新执行poetry install。5.2 我实际踩过的版本兼容问题说一个我记忆比较深的真实情况。EPGF 项目初期同时维护着 Python 3.9 和 Python 3.11 两套环境。某天我想给 3.11 的环境加一个类型的检查库执行poetry add --group dev pyright结果 Poetry 直接拒绝安装提示“当前 Python 版本3.11不满足 pyright 声明的约束”。我以为是镜像源的问题换了官方源也不行最后一看 pyproject.tomlpython 3.9,3.11原来项目创建时锁定了最高支持 3.10我在 3.11 环境里用自然版本校验不过。最后把约束改成3.9,3.12再执行poetry lock重新解析问题才解决。这个案例核心想说明的是pyproject.toml 里的python约束是 Poetry 做解析时的硬性门槛。遇到安装失败先不要怀疑网络先看看项目声明和当前解释器是否匹配。另外Poetry 2.x 和 1.x 在新项目的文件格式上有细微差异。PyCharm 中对 Poetry 的集成不同版本支持程度也不同。如果你用较老的 PyCharm 打开 Poetry 2.x 项目有时候会出现“无法解析 pyproject.toml”的提示。这种情况不用怕在设置里检查 Poetry 插件是否需要更新或者直接把项目当成普通目录打开用终端执行 Poetry 命令即可不影响开发。5.3 团队协作中的本地化补充如果 EPGF 项目不止你一个人开发项目自包含的优势会体现得更彻底。团队成员拉到仓库后只要本机装好了 Python 和 Poetry其余所有操作都被收敛在项目里。我总结了一套团队协作时的标准操作流克隆项目代码git clone repo_url。进入项目目录cd epgf-project。确认 Poetry 配置执行poetry config virtualenvs.in-project true保证每个人的虚拟环境都在项目内部。安装依赖poetry install --with dev。启动开发服务器或者执行测试。整个过程没有手工建虚拟环境、没有手动记录 requirements、没有装包失败后讨论该用哪个源。所有人的环境结构完全一致这就叫“项目自包含”。还有一点要提醒.venv这个文件夹一定要加入.gitignore.venv/ __pycache__/ *.pyc dist/.venv不应该进入 Git 版本控制因为它体积大、包含平台特定路径而且完全可以通过poetry install再生。每个人的系统不同生成的.venv内容也会有差异。仓库里只该保留 pyproject.toml 和 poetry.lock这两个文件才是环境清单的真相来源。我把这套配置方式当成 EPGF 系列所有项目的基础规范。每次都要求先确认virtualenvs.in-project有没有设为true再去写业务代码。工具链的问题如果不前置解决后面越写越被动。最后分享一个小技巧Poetry 在 PyCharm 里最省心的使用方式其实是用它的外部工具配置。在“设置 - 工具 - 外部工具”里把poetry的常用命令配置成按钮比如poetry add、poetry run pytest这样就能在图形界面里一键触达比切到终端敲命令更符合可视化操作的习惯。不过这只是锦上添花先掌握命令行的基础用法图形界面只是为了提高操作效率。个人体会是把工具链在项目层面收敛好后面所有开发动作都会顺畅很多。 
长河君 · 2026/9/9 8:29:08 · 阅读 1.2k Python项目自包含实践：用Poetry实现工具本地化与虚拟环境管理
1. 先说清楚EPGF 项目的“自包含”到底是什么1.1 为什么“工具本地化”是必做环节新手玩 EPGF 这类框架项目时最容易遇到的一个问题不是代码写不出来而是环境先崩了。今天在这台机器上跑得好好的明天换个电脑或者同事拉一下代码一堆依赖报错、Python 版本不一致、Poetry 全局环境互相污染。排查一圈才发现问题全部出在“工具装在了全局”这件事上。所谓“工具本地化”说白了就是把 Python 虚拟环境和 Poetry 的项目级配置全部收敛到项目文件夹内部。项目根目录下生成一个.venv文件夹里面单独放一套干净的解释器和依赖项目的 pyproject.toml、poetry.lock 把依赖版本全部锁死。这样项目本身就是一个自洽的“孤岛”不管放到哪台机器只要安装了基础运行时一条poetry install就能把环境完整还原。在做 EPGF 项目的日常开发时我把这套流程当成默认规范来执行。原因很简单EPGF 这类基础设施级项目依赖项多、版本敏感任何一个包浮动版本都可能引发连锁问题。与其让环境问题反复干扰业务开发不如从一开始就用 Poetry 把依赖管起来并在项目内部完成工具链隔离。这就是标题里说的“工具本地化为必做环节”——它不是加分项而是避免后期返工的前提。1.2 这套方案解决的核心痛点我见过很多新手的真实状态开发一个项目Python 用的是全局解释器装包用 pip今天装一个 requests明天卸一个 numpy偶尔遇到版本冲突干脆pip install --upgrade强制升级。短期看确实“能跑”但等到项目变大你会发现几个很头疼的问题全局环境越来越乱你根本不知道某个包是被哪个项目依赖的也不敢随便卸载。不同项目往往需要同一个包的不同版本全局环境只能装一个来回切换等于自找麻烦。代码提交到 Git 后别人拉下来依赖装不全缺哪个包全靠 README 手工说明。有一天你重装系统或者换电脑想恢复开发环境等于从头再装一遍费时费力还要碰运气。项目自包含 工具本地化这套组合拳正好把上面这些痛点全部按住。Python 解释器不依赖系统级而是项目级依赖不靠requirements.txt简单罗列而是通过 Poetry 在 pyproject.toml 里结构化声明并生成 poetry.lock 锁定精确版本虚拟环境路径统一放到.venv里让 PyCharm 自动识别。任何一个开发成员拿到项目只需要执行poetry install几秒钟到几分钟环境就齐了。这也是我坚持在 EPGF 项目中推行 Poetry 的原因。它的依赖解析速度、分组管理能力、发布集成程度都比裸 pip 好太多。更关键的是Poetry 原生支持“项目内创建虚拟环境”的配置这正好满足我们的本地化要求。2. 环境准备把 Python 和 Poetry 装成“稳定的底座”2.1 Python 安装版本选择与 PATH 问题在讲 PyCharm 和 Poetry 之前必须先把 Python 装明白。很多新手栽在第一步不是装不上而是装完不知道装到哪去了。先强调一个原则不要装预览版老老实实选稳定版。EPGF 项目在开发中一般建议使用 Python 3.10 或 3.11 这类经过大量工具链适配的版本。太老版本可能缺少新语法支持太新版本有些第三方库还没跟上会出现编译报错。以我自己为例主力环境用的是 Python 3.11跑 EPGF 相关的框架和插件完全没有兼容问题。下载安装包时到官方网站下载 Windows installer注意看版本号那串数字比如“3.11.9”后面还有没带 32-bit 还是 64-bit现在基本统一选 64-bit。安装过程中的关键点第一步安装界面的最下方有一个Add Python to PATH复选框一定要勾上。如果不勾后面在命令行里输入python会提示找不到命令到时候再来配环境变量虽然也能补救但没必要绕弯子。安装完成后验证方式很简单打开命令行工具输入python --version如果输出了类似Python 3.11.9的信息说明 Python 已经正常进入系统变量。此时顺手验证一下 pippip --version这两个命令都正常输出说明 Python 的基础链路已经通了。值得一提的是如果你在命令行里执行python后进入的是 Microsoft Store 的应用商店而不是 Python 解释器说明 PATH 顺序有问题或者环境变量被商店应用劫持了这时候去“设置 - 应用 - 高级应用设置 - 应用执行别名”里把两个python.exe的别名关掉就能恢复正常。2.2 Poetry 安装的三种姿势我推荐哪一种Poetry 的安装方式不少我见过的主要有三种官方安装脚本、pipx 隔离安装、直接用 pip 安装。我分别说下利弊。第一种官方 PowerShell 安装脚本(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -这是官方推荐的方式。脚本会把 Poetry 安装到用户目录下的%USERPROFILE%\.local\binWindows 环境不污染全局 Python 环境升级也方便。第二种pipx 安装pipx install poetrypipx 本身就是用来隔离安装 Python 命令行工具的用它装的 Poetry 很干净每个工具都在独立环境里运行。但前提是机器里已经装好了 pipx等于多一步前置操作。第三种直接用 pippip install poetry这种方式最省事也是新手最容易成功的路径。缺点是有可能被全局环境的包冲突影响到。不过对于刚开始学 EPGF 教程的同学我倒是认为可以先直接用 pip 装把主要精力放到项目环境搭建上等玩熟了再换成隔离安装在日常工作中也用得上。装完之后还是老规矩验证一下poetry --version如果提示poetry-poetry之类的错误或者直接提示“不是内部或外部命令”多半是 PATH 没生效。此时重新打开一个命令行窗口再执行一次。如果还是不行检查用户环境变量里有没有把%USERPROFILE%\.local\bin加进去。2.3 让 Poetry 走国内镜像装快不糟心这一步是纯经验补充。默认情况下Poetry 走的官方软件源在国外国内网络环境下创建项目或者添加依赖时经常遇到下载慢、超时、重试失败的情况。解决方法很简单给 Poetry 配置一个国内镜像源。我用的方式在 pyproject.toml 里显式声明[[tool.poetry.source]] name aliyun url https://mirrors.aliyun.com/pypi/simple/ priority primary如果你更习惯用 API 方式也可以一句话配完poetry source add --priorityprimary aliyun https://mirrors.aliyun.com/pypi/simple/配置之后依赖下载速度会明显提升。这里有个细节在 Poetry 2.x 版本里priority primary代表这个源是主源一旦设置了主源PyPI 默认源就会被忽略。如果你需要回退到官方源改成priority default或者直接删掉这个 source 块即可。这一步对新手来说非常实用。我第一次用 Poetry 给 EPGF 项目装依赖时没配镜像一个 Pillow 装了十分钟还没结束最后卡在编译依赖上直接报错。配置完国内源之后整个项目依赖安装时间压缩到两分钟以内体验完全不一样。3. 在 PyCharm 中文版 GUI 中创建 Poetry 项目3.1 先确认 PyCharm 的 Poetry 插件现在很多新手用的 PyCharm 已经带中文语言包了界面路径和英文版略有差异但底层逻辑一样。打开 PyCharm 后先看左侧的“项目”右上角齿轮旁边的“设置”进入“插件”市场搜索 Poetry确认插件已经安装并且处于启用状态。这里有个容易忽略的点PyCharm 的社区版和 Professional 专业版对新项目里的 Poetry 支持程度不同。社区版需要在创建项目后手动配置 Poetry 环境和解释器而专业版可以直接在“新建项目”向导里选择 Poetry。EPGF 教程里的项目一般规模不大社区版完全够用只是操作步骤多一步后面我会把两条路径都写清楚。3.2 GUI 创建流程专业版直接走 New Project 向导如果你的 PyCharm 是专业版创建 Poetry 项目非常简单。打开“文件”菜单选择“新建项目”在弹出的窗口左侧选择“Poetry”。关键字段有三个“位置”项目文件夹路径建议新建一个空目录避免路径里出现中文或空格。“Python 解释器”选择你本机已经装好的 Python 版本Poetry 会用这个版本来创建虚拟环境不需要手动指定.venv后面再改。“Poetry 可执行文件”这里默认会自动识别你安装的 Poetry 路径如果识别不到手动点击文件夹图标定位到poetry.exe所在位置。设置完成之后点击“创建”PyCharm 会自动做三件事在当前目录生成基础项目结构、调用 Poetry 创建虚拟环境、自动激活环境并安装基础依赖。整个过程都是图形化展示的底部可以看到进度条和日志输出。创建完成后看右下角或者右下侧的解释器状态栏如果显示的是“Python 3.11 (.venv)”说明项目已经处于 Poetry 管理的虚拟环境中。此时打开终端面板命令行前会自动带上(.venv)前缀表示当前 shell 已经激活了项目虚拟环境。3.3 命令行创建 PyCharm 导入路线社区版看这里社区版用户没有“Poetry 新建项目”选项卡但完全可以用命令行创建项目再用 PyCharm 打开。这条路线我认为更通用因为不管团队里别人用什么编辑器命令行流程是稳定一致的。先找一个合适的目录执行poetry new epgf-project这条命令会生成一个标准的 Poetry 项目结构epgf-project/ ├── epgf_project/ │ └── __init__.py ├── tests/ │ └── __init__.py ├── pyproject.toml └── README.md进入项目目录后创建虚拟环境cd epgf-project poetry env use python3.11这里的python3.11也可以替换成你机器上具体的 Python 版本或者直接使用python指向系统 PATH 里的默认版本。执行成功后可以在终端确认poetry env info输出里会看到Virtualenv的路径。如果这时候路径显示的是项目根目录下的.venv说明配置已经生效如果不是别急下一章专门讲这个。然后打开 PyCharm选择“打开”并定位到这个项目目录。第一次打开时PyCharm 可能会提示配置解释器我们选择“设置 - 项目 - Python 解释器”点击齿轮图标“添加解释器”选择“现有环境”在 Poetry 虚拟环境路径中定位.venv\Scripts\python.exe。配置完成后写一行代码测试链路import sys print(sys.executable)运行这段代码如果输出的路径里包含.venv说明整个 GUI 配置流程已经串起来了。4. 把 Poetry 做成项目自包含核心配置和文件解读4.1 关键配置让虚拟环境锁定在项目内这里直接给结论Poetry 默认的虚拟环境不一定在项目内部。如果你的电脑里配了缓存目录它可能会把虚拟环境放在用户目录下的AppData\Local\pypoetry\Cache\virtualenvs或者类似位置。这对单机开发影响不大但一旦项目复制、分享、换机这套虚拟环境就跟丢了重新配置还得花时间。我们要做的就是让 Poetry 把.venv直接放到项目目录下。打开 PyCharm 集成的终端执行poetry config virtualenvs.in-project true设置完这一行之后以后每次为这个项目创建虚拟环境Poetry 都会把环境放在项目根目录的.venv文件夹内。你可以用poetry config --list确认配置输出有没有virtualenvs.in-project true。如果你希望多个项目共享同一个虚拟环境缓存目录可以手动指定路径poetry config virtualenvs.path D:\Python\PoetryEnvs但我个人强烈不建议这么干。原因还是那个“本地化”原则项目如果依赖外部路径就有被外部变更波及的风险。老老实实把.venv放进项目文件夹能打包、能随项目走这才是真正的自包含。4.2 pyproject.toml 和 poetry.lock 分别承担什么角色Poetry 项目里有两个文件是核心中的核心pyproject.toml和poetry.lock。pyproject.toml是项目依赖的“声明文件”。它的结构类似这样[tool.poetry] name epgf-project version 0.1.0 description EPGF project toolchain authors [Your Name youexample.com] [tool.poetry.dependencies] python ^3.11 requests ^2.32.0 flask ^3.0.0 [tool.poetry.group.dev.dependencies] pytest ^8.0.0 ruff ^0.4.0 [build-system] requires [poetry-core] build-backend poetry.core.masonry.api依赖声明分为两块主依赖[tool.poetry.dependencies]和开发依赖[tool.poetry.group.dev.dependencies]。主依赖是运行时必须的比如 Flask、requests开发依赖是可选的比如 pytest、ruff只在开发测试时用到。这样做的好处是部署环境可以用poetry install --without dev只装必要依赖不额外拖入测试工具链。poetry.lock则是由 Poetry 自动生成并维护的“锁定文件”。它记录了每个依赖的精确版本、传递依赖、哈希值、来源信息等。只要提交上去团队所有成员执行poetry install时安装的版本完全一致连依赖的依赖都一样不存在“我这边能跑你那边报错”的魔幻问题。这两份文件一个是“我要什么”一个是“实际装了什么”配合起来就是可复现环境的基础。4.3 常用命令操作梳理日常开发足够的命令清单Poetry 的命令体系并不复杂日常开发真正高频使用的就几个。poetry add用于添加一个新的依赖。比如要给 EPGF 项目加入一个解析 Excel 的库poetry add openpyxl添加开发环境专用的依赖poetry add --group dev pytest安装项目的所有依赖poetry install如果只想装主依赖不装开发依赖poetry install --without dev移除一个依赖poetry remove openpyxl更新依赖版本poetry update查看当前环境的依赖树poetry show --tree进入 Poetry 的虚拟环境 shellpoetry shell在虚拟环境中执行一条命令但不进入交互式 shellpoetry run python your_script.py每一次poetry add或者poetry removePoetry 都会自动更新pyproject.toml和poetry.lock不需要手工去改文件这也是比 pip 更省心的一个点。日常开发时我习惯用poetry run配合 PyCharm 终端操作这样可以时刻保持对当前环境的清晰感知避免误操作到全局环境。5. 常见问题与排查实录5.1 几个新手最容易踩的坑下面这些坑都是我实际带新人时反复遇到的问题列成速查表方便自查。问题现象为什么会发生解决办法命令行输入poetry提示“不是内部或外部命令”Poetry 安装后 PATH 未生效或安装目录不在 PATH 中重新打开命令行检查用户环境变量中的%USERPROFILE%\.local\bin必要时手动添加PyCharm 终端激活虚拟环境后Python 版本还是全局版解释器未正确指向.venv在“设置 - 项目 - Python 解释器”里点击“添加解释器 - 现有环境”选择.venv\Scripts\python.exepoetry install下载速度极慢或超时未配置国内镜像源在 pyproject.toml 里增加 aliyun 源或使用poetry source add指令创建项目后找不到.venvvirtualenvs.in-project未设置或旧环境还在缓存路径下执行poetry config virtualenvs.in-project true然后重新poetry env remove并重建环境执行poetry add时提示 Python 版本不满足要求项目声明的python版本约束和新包冲突或当前解释器版本过低检查pyproject.toml中python ^3.11声明确认poetry env use指向正确版本运行程序时报ModuleNotFoundError依赖没安装全或装到了错误环境先确认终端有没有(.venv)前缀再执行poetry install --with devPowerShell 执行安装脚本时报执行策略错误系统默认禁止运行脚本以管理员身份执行Set-ExecutionPolicy RemoteSigned然后再跑安装脚本这里重点提醒一下“执行策略错误”。Windows 的 PowerShell 默认对脚本执行限制比较严格很多新手在安装 Poetry 的第一步就卡住了。看到红色报错不要慌这不是 Poetry 的问题是系统的安全策略。管理员权限的 PowerShell 里执行一次性授权Set-ExecutionPolicy RemoteSigned -Scope CurrentUser之后再次运行官方安装脚本即可。还有一个细节poetry 虚拟环境激活后Windows 终端会显示(.venv)但它其实是一条软链接类型的路径不要在资源管理器里把.venv文件夹移动到别的地方移动之后虚拟环境会失效。正确做法是如果需要移动项目位置直接复制整个项目文件夹然后在新的位置重新执行poetry install。5.2 我实际踩过的版本兼容问题说一个我记忆比较深的真实情况。EPGF 项目初期同时维护着 Python 3.9 和 Python 3.11 两套环境。某天我想给 3.11 的环境加一个类型的检查库执行poetry add --group dev pyright结果 Poetry 直接拒绝安装提示“当前 Python 版本3.11不满足 pyright 声明的约束”。我以为是镜像源的问题换了官方源也不行最后一看 pyproject.tomlpython 3.9,3.11原来项目创建时锁定了最高支持 3.10我在 3.11 环境里用自然版本校验不过。最后把约束改成3.9,3.12再执行poetry lock重新解析问题才解决。这个案例核心想说明的是pyproject.toml 里的python约束是 Poetry 做解析时的硬性门槛。遇到安装失败先不要怀疑网络先看看项目声明和当前解释器是否匹配。另外Poetry 2.x 和 1.x 在新项目的文件格式上有细微差异。PyCharm 中对 Poetry 的集成不同版本支持程度也不同。如果你用较老的 PyCharm 打开 Poetry 2.x 项目有时候会出现“无法解析 pyproject.toml”的提示。这种情况不用怕在设置里检查 Poetry 插件是否需要更新或者直接把项目当成普通目录打开用终端执行 Poetry 命令即可不影响开发。5.3 团队协作中的本地化补充如果 EPGF 项目不止你一个人开发项目自包含的优势会体现得更彻底。团队成员拉到仓库后只要本机装好了 Python 和 Poetry其余所有操作都被收敛在项目里。我总结了一套团队协作时的标准操作流克隆项目代码git clone repo_url。进入项目目录cd epgf-project。确认 Poetry 配置执行poetry config virtualenvs.in-project true保证每个人的虚拟环境都在项目内部。安装依赖poetry install --with dev。启动开发服务器或者执行测试。整个过程没有手工建虚拟环境、没有手动记录 requirements、没有装包失败后讨论该用哪个源。所有人的环境结构完全一致这就叫“项目自包含”。还有一点要提醒.venv这个文件夹一定要加入.gitignore.venv/ __pycache__/ *.pyc dist/.venv不应该进入 Git 版本控制因为它体积大、包含平台特定路径而且完全可以通过poetry install再生。每个人的系统不同生成的.venv内容也会有差异。仓库里只该保留 pyproject.toml 和 poetry.lock这两个文件才是环境清单的真相来源。我把这套配置方式当成 EPGF 系列所有项目的基础规范。每次都要求先确认virtualenvs.in-project有没有设为true再去写业务代码。工具链的问题如果不前置解决后面越写越被动。最后分享一个小技巧Poetry 在 PyCharm 里最省心的使用方式其实是用它的外部工具配置。在“设置 - 工具 - 外部工具”里把poetry的常用命令配置成按钮比如poetry add、poetry run pytest这样就能在图形界面里一键触达比切到终端敲命令更符合可视化操作的习惯。不过这只是锦上添花先掌握命令行的基础用法图形界面只是为了提高操作效率。个人体会是把工具链在项目层面收敛好后面所有开发动作都会顺畅很多。