EPGF 新手教程走到第 12 篇终于要动 PyCharm 了。这一篇其实是社群答疑时被问得最多的话题怎么在中文版 PyCharm 里把 Poetry 用起来并且按 EPGF 的要求做到“项目自包含”。很多人卡住的原因不是 Poetry 有多难而是安装阶段就埋了雷——用全局 Poetry 创建了一堆项目等要迁移、要复现、要交给别人时才发现每个项目都“绑”在一台电脑上。我先把核心结论放在前面这一篇要做的不是“装一个能用就行的 Poetry”而是把 Poetry 项目环境和 Poetry 工具本体都收进项目目录实现真正的项目自包含。这样带来的直接好处是任何一台机器克隆这个仓库只需要一个配好 Python 解释器的 PyCharm就能还原出完全一致的可运行环境。接下来我从为什么、怎么做、怎么验三个阶段展开。1. 先想清楚全局装的 Poetry 为什么会成为“环境炸弹”1.1 三个最典型的隐性风险先说风险这样后面做本地化的时候你才知道自己在防什么。第一个风险是版本漂移。全局 Poetry 是不断升级的你今天创建项目时用的 Poetry 1.8.x半年后可能被系统更新成 2.x。别小看这个大版本切换Poetry 2.x 处理依赖解析、构建后端的方式和 1.x 有不少差异一旦全局升级你老项目的 poetry.lock 在新版本下重新解析很可能出现依赖版本浮动甚至直接解析失败。到时候你都不知道该怪代码还是怪工具。第二个风险是环境串味。全局 Poetry 管理的虚拟环境默认放在用户目录下的统一位置比如~/Library/Caches/pypoetry或者%USERPROFILE%\AppData\Local\pypoetry所有项目共用一个 Poetry 进程和配置。你在 A 项目里执行poetry config改了某个设置B 项目悄悄受影响你在 A 项目里执行poetry updateB 项目如果此时正好打开PyCharm 可能同时检测到并刷新环境两边互相干扰。多人协作时这种“串味”更难排查。第三个风险是环境不可复现。这是最致命的。新同事入职按文档装好全局 Poetry结果他装的版本和你不一样或者他自己折腾过poetry config把虚拟环境路径改了再或者公司 CI 镜像里的 Poetry 又是个老版本。于是同一个仓库在你机器上、在他机器上、在 CI 上跑出来的依赖树可能都不一样。“在我机器上能跑”这句话就是环境不可复现的典型注脚。1.2 自包含的判定标准克隆即所得所以“项目自包含”到底要达到什么效果我习惯用“克隆即所得”来检验。具体有四条克隆仓库后不需要安装任何全局 Python 工具链项目本身就能跑起来。项目目录里自带虚拟环境.venv或者有一条命令能从零生成虚拟环境。所有构建、测试、打包命令都基于项目内工具执行不依赖 PATH 上碰巧存在的某个版本。换一台机器、换一个用户克隆后执行相同命令结果一致。用大白话说仓库带走了项目需要的全部“螺丝刀”不依赖你电脑上恰好装了哪把。1.3 EPGF 为什么把工具本地化列为必做环节EPGF 系列对工程化项目有一条硬性约定工具的安装路径、版本、配置文件必须和项目代码一起纳入管理不能依赖开发者个人电脑的全局环境。这条约定背后是成本计算——环境问题的排查成本往往远高于工具本地化的成本。与其在群里反复发“你poetry --version看一下”“你poetry config --list贴一下”不如一开始就把工具锁进项目里。第 12 篇把这个环节列为必做不是为了折腾新手而是因为越早养成这个习惯后面做 CI、做发布、做团队协作时越省心。2. 开工前检查PyCharm 中文版、解释器和 Poetry 本体的三件套准备2.1 PyCharm 汉化状态确认这一步很简单但我要单独说因为后续所有操作都会用到中文菜单名。如果你还没有汉化操作路径是打开 PyCharm进入设置Windows 是File SettingsmacOS 是PyCharm Preferences汉化后统称“设置”在插件Plugins市场的搜索框里输入Chinese Language Pack安装后重启即可。需要注意一点官方中文语言包和界面版本要匹配。PyCharm 2024.1 对应用 2024.1 的语言包版本。如果你的 PyCharm 版本比较老插件市场可能搜不到对应的语言包这时建议先升级 PyCharm 再汉化。社区版Community Edition一样支持汉化和 Poetry不用为了这个功能上专业版。检查汉化是否生效看两个地方菜单栏是否全是中文新建项目向导里的标题是否显示为“新建项目”。确认无误再往下走。2.2 Python 解释器版本选择Poetry 2.x 需要 Python 3.8 以上我建议直接用 3.11 或 3.12这两个版本是目前生态兼容性最好的梯队第三方包基本都跟上了。至于解释器来源Windows 上直接去 python.org 下载官方安装包安装时务必勾选Add python.exe to PATH。macOS 上推荐用 Homebrew 安装命令是brew install python3.12。有个坑要提前规避Python 安装路径不要带中文和空格也不要装到用户名带中文的目录下。比如C:\Users\张伟\这种路径后续 Poetry 创建环境时偶尔会因为编码问题报一些莫名其妙错误。装到C:\Python312或者C:\Users\dev\Python312这种路径最省心。另一个常见选择是 Anaconda。如果你已经用 Anaconda 管理 PythonPyCharm 同样支持用它作为 Poetry 项目的 base interpreter。但我个人的建议是Poetry 项目尽量用官方 Python别用 conda 环境做 base因为 conda 环境本身又是一层环境抽象和 Poetry 的依赖解析叠加后排查问题时要多考虑一层变量。2.3 Poetry 本体安装先装一个“临时工”这里注意我们要做的项目自包含前提是你得有一个“初始”的 Poetry 用来创建项目。这把“初始”Poetry 只是引导工具后面会把它本地化进项目。安装方式有两种主流方案我做个对比。安装方式命令/操作优点缺点官方安装脚本macOS/Linux 执行curl -sSL https://install.python-poetry.org | python3 -Windows 用 PowerShell 执行官方脚本方式官方、升级方便默认装到用户目录仍属全局工具pipxpipx install poetry自动隔离在独立环境里不污染 Python 全局 site-packages还是全局可访问版本未随项目锁定pip install --user poetry老式常用办法简单容易和项目依赖冲突官方已不推荐对于 EPGF 流程我推荐你用官方脚本装因为后面验证“禁用全局 Poetry”这个环节时官方脚本的卸载路径最清晰。Windows 官方脚本安装后Poetry 会被放到%USERPROFILE%\.local\bin或%APPDATA%\Python\Scripts下注意把对应目录加进 PATH。装完后终端执行poetry --version能打印版本号就说明基础环境通了。到这一步我们只完成了“前置准备”还没有创建任何项目。3. 图形界面创建 Poetry 项目PyCharm 帮你省掉的命令行操作3.1 新建项目向导里的 Poetry 入口打开 PyCharm点击“新建项目”在左侧选择项目类型后右侧会有一个“环境”配置区域。这里的关键在于环境类型下拉框选择Poetry。如果你在列表框里看不到 Poetry说明 PyCharm 版本较老或者没检测到 Poetry 可执行文件稍后我会讲对策。选择 Poetry 后界面会出现几个输入项Poetry 可执行文件PyCharm 默认自动检测如果前面装好了这里一般会自动填上路径没自动填就点旁边的浏览按钮手动选择。基础解释器Base interpreter选你安装好的 Python 3.11/3.12。虚拟环境目录PyCharm 通常默认填.venv保持默认即可。填完后点击“创建”PyCharm 就会开始干活。你会看到底部状态栏出现与 Poetry 相关的进度提示第一次创建时要下载和解析依赖稍微有点耐心。创建完的项目结构里会自动带上pyproject.toml这比手动poetry new再导入要省事得多。3.2 为什么 PyCharm 能自动检测到 PoetryPyCharm 检测 Poetry 的机制并不复杂它在 PATH 环境变量里查找poetry或者poetry.exe找到了就把路径显示出来找不到就留空。所以前面安装完 Poetry 后没有重开终端或者没有配 PATH这里就检测不到。如果你在 PyCharm 新建项目向导里看到 Poetry 可执行文件是空的先回终端执行poetry --version确认命令可用然后重启 PyCharm 再试。如果你已经把 Poetry 装成了项目自包含形态后面第 4 节的内容也可以在这里直接浏览选择项目内的 Poetry 可执行文件路径PyCharm 完全支持。这一点很关键说明 PyCharm 并不强制要求全局 Poetry它只是需要一个可执行文件路径至于这个文件在全局还是项目内PyCharm 不关心。3.3 创建完成后的第一件事检查虚拟环境落在哪点“创建”后PyCharm 会调用 Poetry 的 new/init 逻辑生成项目结构然后创建虚拟环境。项目打开后第一件事不是写代码而是确认虚拟环境位置。操作方法进入“设置 项目 Python 解释器”看右侧当前解释器的路径。如果解释器路径长这样C:\Users\你的用户名\AppData\Local\pypoetry\Cache\virtualenvs\epgf-demo-xxxxx\Scripts\python.exe那说明虚拟环境被创建到了 Poetry 的全局缓存目录里也就是说当前项目还没实现自包含。这是默认状态不用慌下一节就来改。如果解释器路径是这样D:\projects\epgf-demo\.venv\Scripts\python.exe说明你的 Poetry 已经配置过virtualenvs.in-project可以直接跳到第 5 节做验证。4. 工具本地化核心动作把 Poetry 和 .venv 一起“关进”项目目录4.1 第一步修改 Poetry 的虚拟环境策略回到 PyCharm 底部打开“终端”Terminal面板。执行poetry config virtualenvs.in-project true这条命令的作用是告诉 Poetry以后凡是本用户创建的虚拟环境一律创建在项目根目录下的.venv文件夹里不要再往全局缓存目录塞。如果你希望在项目级别固化这个配置让它随着仓库走可以再加一条poetry config --local virtualenvs.in-project true加了--local之后配置会写入项目根目录的poetry.toml文件。这个文件应该提交到版本库这样团队里每个人克隆后执行poetry install都会自动遵守“虚拟环境必须待在项目里”的约定。这里解释一下不带--local是写在用户级配置文件config.toml里影响的是你这台机器的所有 Poetry 项目带--local则只影响当前项目。EPGF 的要求是项目级固化所以两条建议都执行。4.2 第二步删除旧虚拟环境并重新生成光改配置没用旧的虚拟环境还躺在全局缓存里得先清掉。在终端执行poetry env remove --all这条命令会把这个项目关联的所有虚拟环境全部删除。删除后再执行poetry installPoetry 会按照新的配置在项目根目录创建.venv并安装pyproject.toml里声明的全部依赖。完成后验证一下poetry env info输出里会有一个Path字段如果指向项目目录下的.venv说明这一步成功了。我在实测中碰到过一种情况执行完poetry install后终端提示环境已经存在但项目里就是没有.venv。后来发现是 PyCharm 自带的嵌入终端没有重新加载环境变量项目里显示的是旧解释器。遇到这种情况不要急重启 PyCharm 或者重新打开终端面板即可。4.3 第三步把 Poetry 本体也装进项目到这里虚拟环境已经本地化了但“工具本地化”还没做完——Poetry 命令本身仍然是全局的。要做到 EPGF 要求的彻底自包含有两种方案。方案 A推荐折中用 pipx 隔离全局 Poetry。执行pipx install poetrypipx 会把 Poetry 装在一个独立环境里避免和项目依赖混在一起版本由你控制。但严格来说它仍是全局工具只是不污染环境。如果你不想过度设计用这个方案已经能解决 80% 的问题。我自己在维护一些中大型项目时用的就是这套——全局只有一个 pipx 装的 Poetry每个项目各自带.venv互不干扰。方案 B彻底本地化在项目目录里自建一个工具虚拟环境把 Poetry 装进去。具体命令如下Windows 用Scripts目录macOS/Linux 用bin目录python -m venv .tools .tools\Scripts\python.exe -m pip install poetry1.8.3装完后项目根目录出现.tools文件夹里面带了一个指定版本的 Poetry。然后需要在 PyCharm 里指向它进入“设置 工具 Python 集成工具”在“打包”区域的 Poetry 可执行文件输入框里浏览选择项目内.tools里的 poetry或 poetry.exe应用保存。这样做的好处是Poetry 的版本被钉死在项目里任何人克隆后只要执行同样的命令就能得到完全一致的工具版本。团队里甚至可以在pyproject.toml的 dev 依赖里声明 poetry 版本也可以用一个项目脚本自动重建.tools把这个过程固化下来。对于 CI/CD 要求极其严格的团队方案 B 是更稳妥的选择因为构建镜像里连全局 Poetry 都不用装直接调项目内的.tools即可。方案 B 有个细节要注意项目根目录下的.gitignore要先写好确定.tools是提交到仓库还是忽略。如果团队机器平台一致都是 Windows可以考虑提交如果跨平台建议忽略并在 README 或项目脚本里写明重建命令。我个人的做法是忽略.tools用项目内脚本一键重建避免平台差异带来的兼容问题。4.4 本地化之后的 .gitignore 与文件清单完成以上三步后项目根目录应包含这些关键文件pyproject.toml项目元数据和依赖声明。poetry.lock精确锁定依赖版本必须提交。poetry.toml项目级 Poetry 配置如果你使用了--local建议提交。.venv虚拟环境加入.gitignore。.tools工具环境方案 B根据团队决策决定是否忽略。.gitignore里至少要有这几行.venv/ .tools/ __pycache__/ *.pyc .pytest_cache/注意顺序.venv/和.tools/必须在提交前就写好否则一旦误提交后面清理历史记录很麻烦。5. 自包含验证清单克隆到新机器也能直接跑才算数5.1 五步验证法配置做完了怎么证明真的自包含了我总结了一套五步验证法每一条都可以实际操作检查.venv是否存在于项目根目录且 PyCharm 解释器指向它。执行poetry check确认pyproject.toml与poetry.lock一致。检查poetry.toml项目配置是否已提交到版本库。在干净终端里执行poetry install --sync看能否顺利完成任务。最关键一步模拟新机器验证项目脱离全局 Poetry 可运行见 5.2。5.2 实操演示模拟一台没有 Poetry 的机器这一步特解压。先找到全局 Poetry 的可执行文件路径在终端执行where poetryWindows或which poetrymacOS/Linux把路径记下来。然后把这个可执行文件临时改个名比如poetry改成poetry_bak模拟“本机没有全局 Poetry”。改完之后在 PyCharm 里关闭项目再重新打开。这时候按道理PyCharm 已经无法通过 PATH 找到全局 Poetry 了但项目依然能正常运行。验证方法在终端执行python --version确认进入的是项目.venv。直接运行项目主入口脚本看依赖导入是否正常。在 PyCharm 里打开“设置 项目 Python 解释器”确认解释器路径仍是项目内.venv。如果项目有测试运行测试命令确认测试通过。如果上面全部通过说明项目已经做到了工具本地化即便全局环境坏掉项目也能独立运行。验证完后把临时改名的 poetry 改回来即可。我在给团队做培训时经常现场演示这个操作效果比讲十页文档都好——大家亲眼看到全局 Poetry 被“禁用”后项目照常跑才能真正理解自包含的价值。5.3 两个常见误解澄清误解一项目自包含 把 .venv 提交到 git。不是。虚拟环境包含大量机器相关的绝对路径和编译产物提交后既臃肿又不可移植。自包含指的是工具链、版本约束、配置文件的“定义”收进项目而不是把“产物”收进项目。正确的复现方式是克隆后执行poetry install由 Poetry 根据poetry.lock精确重建环境。误解二项目自包含 完全离线。也不是。自包含解决的是“环境和工具版本的可复现性”依赖包仍然通过 PyPI 或私有源下载。离线分发是另一个话题需要引入本地 wheel 仓库和自包含是两个维度。别把这两个概念混在一起否则会在设计上过度设计平白增加复杂度。6. 新手高频报错排查从“找不到 poetry”到“虚拟环境跑到 C 盘”6.1 报错Poetry 无法识别 / 系统找不到指定的路径这个报错出现在 PyCharm 终端里执行poetry命令时。根因基本就是 PATH 没配置好。Windows 下官方安装脚本装完后Poetry 的路径通常在%USERPROFILE%\AppData\Roaming\Python\Scripts或%USERPROFILE%\.local\bin把对应目录加进系统 PATH重开终端再试。macOS 用户则大概率是~/.local/bin没在 PATH 里。排查命令先where poetry/which poetry如果能找到但执行报错再检查文件本身是否存在、是否为有效脚本。还有一种情况PyCharm 内嵌终端没有继承系统 PATH 的新值重启 PyCharm 即可解决。6.2 虚拟环境被创建到了项目目录之外的位置很多人明明执行了poetry install结果在项目目录里死活找不到.venv。这时候去 Poetry 全局缓存目录看一眼多半在那儿。根本原因就是没有设置virtualenvs.in-project或者设置后被全局配置覆盖。排查方法执行poetry config --list看virtualenvs.in-project的值。如果显示false说明.venv会被创建到virtualenvs.path指定的目录。修复方式就是第 4 节的两条 config 命令。还有个细节如果项目里已经有一个poetry.toml--local配置它的优先级高于用户级配置。所以最稳妥的排查顺序是先看项目里有没有poetry.toml再看用户级配置config.toml。poetry config --list输出的内容里会标注配置来源仔细看就明白了。6.3 中文版 PyCharm 里找不到对应菜单汉化之后菜单名的映射是不少新手卡壳的地方。我列几个高频操作的中英文对照操作英文界面中文界面设置File Settings / PyCharm Preferences文件 设置插件市场Settings Plugins Marketplace设置 插件 市场Python 解释器Settings Project Python Interpreter设置 项目 Python 解释器终端面板View Tool Windows Terminal视图 工具窗口 终端Poetry 可执行文件配置Settings Tools Python Integrated Tools设置 工具 Python 集成工具有时候中文界面下找不到 Python 解释器入口是因为工具窗口是浮动折叠的需要从“视图 工具窗口”里把项目结构调出来或者直接用快捷键Alt1打开项目树右键项目名也能进入解释器设置。中文版只是翻译了菜单功能和英文版完全一致不要因为名字对不上就以为自己装错了版本。6.4 解释器选错base interpreter 指向 conda 或系统 Python新建 Poetry 项目时base interpreter 选错是另一个高频问题。如果基础解释器是 Anaconda 的python.exePyCharm 在创建 Poetry 环境时会做一些额外的包路径处理偶尔会把 conda 环境里的包混进来。排查方式在 PyCharm 的解释器设置里看“包”列表如果发现不是来自.venv的奇怪路径多半是 base interpreter 的问题。解决办法很简单删除这个环境重新选择官方 Python 作为 base interpreter 再创建一次。别舍不得那几分钟的安装时间环境干净比什么都重要。6.5 一个容易被忽略的小问题安装目录名与项目路径含中文哪怕解释器本身没问题项目路径含中文也可能让 Poetry 在解析路径时出错。Windows 下编译器在处理 Unicode 路径时不够稳定我见过不少案例同样的项目路径从D:\项目\demo改成D:\projects\demo后所有报错全部消失。EPGF 的工程规范里干脆约定开发环境一律使用英文路径。这个约定听起来有点“洁癖”但实操中确实能省掉很多不可名状的诡异错误。还有一个相关的坑pyproject.toml里的项目name字段如果包含中文或大写字母Poetry 在创建虚拟环境时生成的目录名可能带转义字符比如epgf-demo-xxxxx这种虽然不影响使用但在排查环境路径时会让人困惑。建议项目 name 一律用小写英文字母和连字符这也是 PEP 规范推荐的做法。最后分享一个实际操作中的习惯。我在做完项目自包含之后一定会把第 5 节的验证清单放进项目的CONTRIBUTING.md里并附上.tools的重建命令。这不是多此一举而是为了让任何一个后来者都清楚“这个项目的工具链是怎么变出来的”。工具本地化的一次性成本不算低但它换来的是后续每次环境迁移、每次新人入职、每次 CI 构建都不再靠运气。以我的经验做过一次完整自包含改造的项目往后会越用越顺手而一直靠全局环境撑着走过来的项目迟早要还一笔更大的环境债。第 13 篇我打算接着聊 poetry.lock 的冲突合并策略那是多人协作时另一个绕不开的硬骨头到时候见。