规范Python项目目录结构需分层明确、职责分明：src/放主代码，tests/平级存测试，scripts/放可执行脚本，configs/集中配置，requirements/拆分依赖；命名全小写下划线，测试文件以test_开头或_test.py结尾，__init__.py显式导出接口，敏感配置.gitignore过滤，根目录用pyproject.toml管理依赖与工具，CI强制代码检查，README和make封装提升协作效率。
Python项目文件管理不是随便建个文件夹就完事，关键在结构清晰、职责分明、方便协作和部署。一个规范的目录结构能让新成员快速上手，让CI/CD流程稳定运行，也避免import混乱或路径硬编码出错。
核心目录结构建议
推荐采用分层明确、按功能隔离的布局，典型结构如下（根目录下）：
-
src/：主代码包（如
src/myproject/），含所有可导入模块，__init__.py齐全；不把代码直接放根目录 -
tests/：与
src/平级，用pytest结构（如tests/test_core.py），支持python -m pytest直接运行 -
scripts/：存放可执行脚本（如数据清洗、定时任务），不混入业务逻辑，用
#!/usr/bin/env python+if __name__ == "__main__": -
configs/：配置文件集中地（
dev.yaml,prod.env等），避免写死在代码里 -
requirements/：拆分依赖（
requirements/base.txt,dev.txt,prod.txt），用pip install -r requirements/prod.txt精准安装
命名与组织细节要点
小习惯影响大体验，这些细节常被忽略但极易引发问题：
- 包名、模块名全小写+下划线（
data_loader.py），不用驼峰或中划线（DataLoader.py或data-loader.py会导致 import 失败） - 测试文件必须以
test_开头或_test.py结尾，pytest 才能自动发现 -
__init__.py不留空——显式导出公共接口，例如：from .core import run_pipeline，再在外部from myproject import run_pipeline - 敏感配置（密钥、数据库密码）绝不提交到 Git，用
.gitignore过滤*.env,secrets.yml等，并在 README 中说明如何生成
环境与依赖管理实践
依赖混乱是线上事故高频原因，靠规范约束比靠人工记忆更可靠：
立即学习“Python免费学习笔记（深入）”；
- 项目根目录放
pyproject.toml（替代 setup.py），定义构建系统、依赖、lint 工具等，现代 Python 工具链（pip, poetry, hatch）都优先读它 - 开发时用
poetry install或pip install -e ".[dev]"安装可编辑模式，确保本地 import 路径与生产一致 - 每次更新依赖后运行
pip freeze > requirements/locked.txt（或用poetry export -f requirements.txt），部署时严格按锁文件安装 - 禁止在代码中用
os.chdir()切换工作目录——改用pathlib.Path(__file__).parent获取相对路径
自动化检查与文档同步
规范要落地，得靠工具兜底和轻量文档支撑：
- 在
pyproject.toml中配置flake8/black/mypy，CI 流程中强制校验，失败即阻断合并 - 根目录放简洁
README.md，包含：快速启动命令（make init）、配置说明、测试运行方式、常见问题（如“ImportError: No module named 'xxx'” → 检查是否在 src 外运行） - 用
make或just封装常用操作（make test,make format,make deploy），降低新人使用门槛 - 定期运行
pylint --fail-under=8 .或bandit -r src/扫描安全与质量风险，结果集成进 CI 报告
不复杂但容易忽略——结构定下来，团队写代码、测代码、发代码就都有了共同语言。坚持几周，会明显减少“为什么我本地跑得通，服务器报错”的沟通成本。
