中小团队应采用pyproject.toml+poetry+.pre-commit-config.yaml三件套实现标准化开发：poetry确保依赖一致，pyproject.toml统一工具配置，pre-commit拦截低级错误，IDE需正确集成poetry环境。
直接上结论：不靠人盯人，靠 pyproject.toml + poetry + .pre-commit-config.yaml 三件套落地，其他方案在中小团队（2–10人）中基本等于摆设。
用 poetry 替代 pip + requirements.txt 管理依赖
常见错误现象：pip install -r requirements.txt 在不同机器上装出不同版本；pip freeze > requirements.txt 导出全量依赖，包含大量间接依赖，不可维护。
为什么这样做：poetry 锁定的是 poetry.lock，它记录了每个包的精确版本、哈希值和依赖树，保证 poetry install 在任何环境还原完全一致的依赖图。
- 初始化项目时统一执行：
poetry init→ 回车接受默认，再手动编辑pyproject.toml的[tool.poetry.dependencies]区块 - 只允许通过
poetry add requests或poetry add pytest@^7.0添加依赖，禁止直接改pyproject.toml后手写poetry lock - CI/CD 流水线中必须用
poetry install --no-root（跳过主项目安装，只装依赖），避免误触发构建逻辑 - 团队成员首次拉代码后，只需
poetry install，无需手动source .venv/bin/activate—— poetry 自动管理虚拟环境位置
pyproject.toml 必须收敛所有工具配置
使用场景：避免 PyCharm、VSCode、CI 脚本各自维护一套 flake8/black/mypy 配置，导致本地格式化后 CI 报错。
立即学习“Python免费学习笔记（深入）”；
参数差异：black 默认是 88 字符，但团队若用宽屏显示器可调为 100；mypy 的 disallow_untyped_defs = true 是强约束，而 ignore_missing_imports = true 仅用于 stubs 场景，不能全局开启。
实操建议：
- 把
[tool.black]、[tool.flake8]、[tool.mypy]、[tool.isort]全部写进pyproject.toml，删掉setup.cfg和pyproject.toml外的任何配置文件 - black 和 isort 的顺序必须固定：先
isort整理 import，再black格式化，否则 black 可能破坏 import 分组 - 在
[tool.pytest.ini_options]中指定testpaths = ["tests"]和python_files = "test_*.py"，避免 pytest 自动扫描非测试文件
用 pre-commit 拦截本地低级错误
常见错误现象：有人提交带 print() 的调试代码、未处理的 except:、或 tab 混入空格；等 Code Review 时才发现，已污染 Git 历史。
为什么这样做：pre-commit 在 git commit 前自动运行检查，失败则中断提交，不依赖开发者自觉。
实操建议：
- 在项目根目录放
.pre-commit-config.yaml，内容至少包含：black、flake8、isort、pylint（可选）、check-yaml（防 CI 配置写错） - 团队首次使用前统一执行：
pre-commit install；CI 中也加一步pre-commit run --all-files作兜底 - 禁用
autofix类 hook（如end-of-file-fixer），避免不同人 pre-commit 版本不一致导致换行符冲突 - 对
pyproject.toml本身做校验：加check-toml，防止语法错误导致 poetry 解析失败
PyCharm / VSCode 配置必须导出为机器可读文件
性能影响：IDE 若未识别 poetry 环境，会显示大量 false positive 的 import error；若未启用 black on save，团队格式风格必然分裂。
容易踩的坑：PyCharm 的 “Project Interpreter” 手动指向 .venv 路径，但 poetry 默认把环境建在 ~/Library/Caches/pypoetry/virtualenvs/（macOS）或 %LOCALAPPDATA%\pypoetry\Cache\virtualenvs\（Windows），路径不固定。
实操建议：
- PyCharm：Settings → Project → Python Interpreter → 点右上角齿轮 → Add → Poetry Environment → 保持 Base interpreter 为系统 Python，Poetry executable 填
poetry（确保已加入 PATH） - VSCode：安装 Python 插件后，按
Ctrl+Shift+P→ “Python: Select Interpreter” → 选中 “Poetry Environment” 项（需已运行过poetry install） - 禁止在 IDE 中手动设置
black或flake8路径 —— 它们会自动从pyproject.toml读取配置 - 团队共享
.idea/codeStyles/Project.xml（PyCharm）或.vscode/settings.json（VSCode），但只保留与格式化、linter 相关字段，删掉个人偏好类配置（如字体大小）
最常被忽略的一点：pyproject.toml 里 [build-system] 的 requires 必须显式声明 "poetry-core"，否则某些 CI 镜像（如 python:3.12-slim）因缺少构建后端而 pip install 失败；这个细节在本地开发时不会暴露，一到部署就卡住。
