PyCharm
同一份源码，可能被三套 Python 同时解释
外部终端执行 pytest 全部通过，PyCharm 编辑器却把导入标红；点击运行后又出现另一个结果。团队常把它归咎于索引，清缓存后症状短暂变化，根因仍在：终端通过版本管理器选择 Python，PyCharm 项目绑定了旧 virtualenv，运行配置又显式覆盖了解释器或工作目录。源码只有一份，解释器、包集合与导入路径却已经分叉。
PyCharm 的项目边界不是“打开了哪个文件夹”这么简单。项目目录给出源码与配置位置，解释器决定执行平台，虚拟环境决定包集合，pyproject.toml、锁文件或 requirements 描述依赖，运行配置再加入工作目录、参数和环境变量。只有这些对象指向同一项目事实，代码分析、测试、调试和 CI 才有比较意义。
先把产品能力和安装责任讲清楚
PyCharm 当前采用统一产品入口，免费的核心功能与需要订阅的 Pro 能力在同一产品中按许可生效。团队应按实际需要判断本地 Python 编辑、运行和测试是否足够，还是确实需要 Web 框架、数据库、远程解释器等高级能力；不能继续沿用旧的 Community/Professional 两套安装想象。动态能力边界以 Unified PyCharm 和订阅页面为准。
个人开发机通常从 JetBrains Toolbox 安装稳定版本，试点机器并存下一版本。软件分发系统明确时可用官方 standalone 包；完全离线要同时准备匹配 OS/CPU 的安装包、允许的激活方式、批准插件、Python 发行包与依赖镜像。只有 IDE 安装成功而 PyPI、conda channel 或 uv 下载源不可用，不算离线开发环境完成。
第一次启动先从 Help | About 记录产品 build、IDE runtime、OS 和架构，再确认许可、代理与企业 CA。插件与 IDE 同权限运行，Required Plugins 只提示缺失，不是准入控制。团队批准的是发布者、来源、版本和兼容范围，而不是一个不变的插件名称。账号、激活信息、内网索引地址与真实证书不进入截图或仓库。
升级时保留旧 IDE 实例，用代表项目完成环境创建、依赖同步、类型检查、测试、断点和停止。不要把 PyCharm、Python 版本、依赖解析器与 lockfile 在同一次变更里全部升级，否则失败后无法判断是哪一层改变。
解释器是执行边界，不是状态栏装饰
PyCharm 解释器配置支持系统 Python、virtualenv、Pipenv、Poetry、uv、Hatch 与 conda 等本地环境；Pro 能力还覆盖 SSH、Docker、Docker Compose 与 WSL 等目标。无论入口如何，IDE 最终都必须知道一个实际 Python 可执行文件，以及这个解释器对应的包与路径。
打开仓库后先在外部终端保存基线：
python --version
python -c "import sys; print(sys.executable); print(sys.prefix); print(sys.path[0])"
python -m pip --version
Get-ChildItem pyproject.toml,requirements*.txt,uv.lock,poetry.lock,Pipfile.lock -ErrorAction SilentlyContinuePyCharm 状态栏与 Settings | Python | Interpreter 应指向项目认可的环境。如果仓库使用 .venv，Windows 通常选择 .venv\Scripts\python.exe，macOS/Linux 选择 .venv/bin/python。虚拟环境目录不提交 Git；提交的是创建环境所需的 Python 版本约束、依赖声明与任务入口。
同一个基础 Python 可以派生多套虚拟环境。PyCharm 下拉框中名字相近不能证明环境相同，必须比较可执行文件绝对路径与 sys.prefix。环境被移动、基础解释器卸载或目录被清理后，Invalid environment 应通过路径和版本证据修复，而不是给旧条目换一个显示名称。
依赖主源只能有一个，IDE 不替仓库发明声明
Python 项目可能使用 pyproject.toml、锁文件、requirements 或 conda 环境文件。团队先确定哪个文件是发布和 CI 的主源，再选择相应工具；PyCharm 的包窗口只能操作所选解释器，不应该成为未记录依赖的唯一来源。开发者在 GUI 点击安装成功但没有更新仓库声明，下一台机器仍会缺包。
以 uv 管理的项目为例，最小链路可以是：
uv python pin 3.12
uv sync --frozen
uv run python -c "import sys; print(sys.executable)"
uv run pytestPoetry、Pipenv 或 pip-tools 项目应换成仓库规定的冻结命令。关键不在工具名，而在解析不擅自更新锁文件、测试使用锁定环境、PyCharm 绑定同一解释器。内网源还要验证索引元数据、包下载、哈希/签名策略和撤销；不能为了修复证书失败使用 --trusted-host 长期绕过 TLS。
requirements 文件若同时包含顶层意图和完整传递依赖，团队要说明生成方式。直接在不同机器 pip freeze 并合并，容易把平台相关包、本地路径和偶然工具带入基线。PyCharm 看到的“已安装”状态只描述当前环境，不等于依赖声明正确。
用错误解释器稳定复现一次导入失败
下面的实验创建两个隔离环境，只在其中一个安装本地包。它能证明“项目目录相同”不能替代解释器选择。
$lab = Join-Path $env:TEMP "pycharm-interpreter-lab"
Remove-Item -Recurse -Force $lab -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path (Join-Path $lab "src\demo_pkg") -Force | Out-Null
@'
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "pycharm-interpreter-lab"
version = "0.0.0"
'@ | Set-Content -Encoding utf8 (Join-Path $lab "pyproject.toml")
@'
VALUE = "interpreter-ok"
'@ | Set-Content -Encoding utf8 (Join-Path $lab "src\demo_pkg\__init__.py")
@'
from demo_pkg import VALUE
print(VALUE)
'@ | Set-Content -Encoding utf8 (Join-Path $lab "check.py")
py -3 -m venv (Join-Path $lab ".venv-good")
py -3 -m venv (Join-Path $lab ".venv-empty")
& (Join-Path $lab ".venv-good\Scripts\python.exe") -m pip install -e $lab
& (Join-Path $lab ".venv-good\Scripts\python.exe") (Join-Path $lab "check.py")
& (Join-Path $lab ".venv-empty\Scripts\python.exe") (Join-Path $lab "check.py")
$negativeExit = $LASTEXITCODE
"negative_exit=$negativeExit"
Remove-Item -Recurse -Force $lab正例输出 interpreter-ok；空环境触发 ModuleNotFoundError 并返回非零退出码。在 PyCharm 中先选择空环境复现红线与运行失败，再切换到 good 环境。若编辑器已经不标红但运行仍失败，应比较代码分析解释器和运行配置解释器；若两者都正确，再检查工作目录和项目安装方式。
这个实验使用 editable install 让包结构进入解释器环境，避免靠手工添加 source root 或 PYTHONPATH 掩盖打包问题。PyCharm 允许管理 interpreter paths，这些路径会进入分析和运行环境；只有项目模型确实需要时才添加，并把原因写进团队文档。否则本机补一条路径会让 CI 的真实缺陷消失。
测试、运行与调试必须复用项目环境
PyCharm 的 pytest/unittest 配置应选择项目解释器和仓库根，参数与 CI 保持可比较。先在外部终端运行 python -m pytest，再从 IDE 运行同一测试。使用 python -m 能明确当前解释器负责加载工具，避免 pytest.exe 来自另一环境。
最小调试不是只看到 Debug 窗口。应在业务入口或测试设置断点，确认调用栈中的文件属于当前 clone，sys.executable 指向预期环境，工作目录与配置一致；停止后子进程、开发服务器和调试端口都退出。框架自动重载可能启动父子两个进程，断点只命中其中一个时要先判断 reloader 模型，不能不停切换断点。
共享 Run Configuration 时使用项目宏或相对路径，环境变量只保留名称和无敏感默认值。数据库 URL、云密钥、私有索引 token、Django secret 等由本机环境或密钥工具注入。.run 或 .idea 中出现真实值后，删除文件不足以解除风险，还要轮换凭证并检查历史。
Jupyter、数据科学与 Web 框架能力会引入 kernel、解释器、浏览器、服务端口和数据库等更多对象。每增加一个入口，都要能回答代码在哪里执行、依赖来自哪个环境、输出写到哪里、停止动作是否清理进程。产品功能丰富不能替代运行边界说明。
远程解释器改变的是代码与进程所在位置
SSH、Docker、Compose 或 WSL 解释器不是本地解释器的另一个名字。PyCharm 会在目标侧运行 Python、测试和调试 helper，并在本地保留分析所需的 skeleton/source 信息。版本升级可能更新远端 helper；路径映射、文件同步和容器生命周期也会影响断点与导入。
接入远程目标前，先证明目标环境能独立执行仓库任务，再让 PyCharm 连接。SSH 私钥、用户名、内部 host 与代理不提交项目；Docker socket、volume mount、容器用户和 Secret 交付按 Dev Containers/容器边界审查。远程失败时分别收集连接、解释器、同步、helper、依赖和目标进程证据，不能把所有问题统称为“远程调试失败”。
团队若只需要远端算力或 Linux 依赖，也要比较 JetBrains Remote Development：远程解释器仍由本地 IDE 承担主要 UI 和部分项目状态，Remote Development 则把完整 IDE backend 放在远端。两者的资源、网络、许可与清理责任不同。
类型分析、索引与运行结果要允许不一致，但必须可解释
PyCharm 的代码分析会结合类型注解、stubs、解释器包、source roots 和自身推断。运行成功而编辑器标红，可能是动态导入、缺失 stub、错误解释器或项目路径配置；编辑器无警告而运行失败，也可能来自未覆盖分支、条件依赖或运行配置偏差。不要把任何一边自动宣布为真，先用具体 import、sys.path 和测试结果定位差异。
索引属于派生状态。切换依赖或解释器后，先等待/触发项目模型更新，确认包确实安装到目标环境；只有输入已经一致而符号仍错误，再重建索引。Restore Default Settings 会备份配置后重置 IDE，但它会改变整个产品设置，适合作为隔离诊断，不是团队日常修复按钮。
缓存清理从项目环境开始：关闭进程，确认 .venv 可由锁定声明重建，删除后按正式入口重建并跑测试。pip/uv/Poetry/conda 缓存各有 owner 和离线价值，不能用一条全局递归删除清空。PyCharm system 目录、Local History 与日志最后处理，清理前保存未提交工作和必要证据。
常见故障从解释器指纹开始分型
终端通过、IDE 导入失败时，先比较 sys.executable、sys.prefix、工作目录和依赖版本，再看 source root。若 IDE 使用另一环境，修正绑定并重跑；若同一环境只在 IDE 失败，再检查项目路径与索引。
测试窗口通过、CI 缺包时，检查依赖是否只通过 GUI 安装、editable path 是否指向本机目录、环境是否继承全局 site-packages。修复应更新仓库依赖主源并在干净环境冻结安装，不把整个 .venv 上传仓库。
断点不命中时，确认目标 PID、reloader/worker 模型、解释器、源码路径和是否运行优化或生成代码。远程场景再核对 path mapping 与 helper。修复后重新启动干净会话，用同一请求命中断点并正常停止。
依赖下载或登录失败时，分开 PyPI/私有索引、JetBrains 账号、插件仓库和代理 CA 链。浏览器成功不代表 pip 或 IDE 客户端成功，关闭 TLS 校验更不是修复。保留脱敏的目标、issuer、退出码和客户端配置路径，交给对应 owner。
团队基线最终要能在干净环境重建
正式支持 PyCharm 的证据来自干净 clone：选择受支持 Python，按仓库入口创建环境，冻结安装不修改依赖主源，测试通过，断点命中，停止无残留，团队配置不含秘密，批准插件可重建，旧 IDE 实例能够回退。个人同步只恢复使用习惯，不替代这条链。
大型 monorepo 或数据项目还要量化索引时间、内存、虚拟环境与数据集磁盘占用。优化应先缩小真实内容根、把生成物和大数据移出分析范围、按 workspace/member 建模；关闭全部 inspection 或随意追加解释器路径会降低噪声，也会让错误更晚暴露。
选择 PyCharm 而不是 VS Code、Jupyter 前端或通用 IntelliJ 产品，应说明收益来自哪里：Python 解释器、框架、测试、数据库、远程目标或结构化重构是否真的减少组合成本。退出机制同样重要。即使取消订阅或更换 IDE，仓库仍必须能通过命令创建环境、安装依赖、运行测试和启动服务；IDE 项目文件不能成为唯一构建说明。