很多 Python 项目一开始都能跑，但随着模块增多、脚本变杂、测试补不上，目录结构很快就会拖累维护效率。这里结合一套常见的 CentOS 项目布局，按“文件放哪儿、各自负责什么、后续如何协作”三个问题拆开说明，帮助你判断哪些约定适合在项目初期就固定下来。
一套常见的 Python 项目结构
如果你想在 CentOS 上把 Python 项目整理得清晰、可安装、方便协作，下面这类结构基本能覆盖多数开发场景：
my_project/
├── README.md
├── LICENSE
├── requirements.txt
├── setup.py
├── .gitignore
├── docs/
│ ├── conf.py
│ ├── index.md
│ └── ...
├── src/
│ ├── __init__.py
│ ├── module1/
│ │ ├── __init__.py
│ │ ├── file1.py
│ │ └── file2.py
│ ├── module2/
│ │ ├── __init__.py
│ │ ├── file1.py
│ │ └── file2.py
│ └── main.py
├── tests/
│ ├── __init__.py
│ ├── test_module1.py
│ ├── test_module2.py
│ └── ...
└── scripts/
├── script1.py
├── script2.py
└── ...这套布局的核心思路很直接：根目录放项目说明和安装信息，src/ 专注业务代码，tests/ 跟进验证，docs/ 负责文档，scripts/ 留给独立执行的命令行脚本。目录边界清楚之后，扩展和交接都会轻松很多。
根目录文件分别负责什么
根目录是别人接触项目时最先看到的部分，信息是否完整，直接影响上手成本。
README.md、LICENSE 和依赖声明
README.md：相当于项目门面，用来说明项目用途、安装方式和基本使用方法。LICENSE：明确项目的使用和分发权限，开源项目尤其不能缺。requirements.txt：集中列出第三方依赖，便于统一安装环境。
安装与版本控制相关文件
setup.py：负责安装和打包，有了它就可以直接使用pip install .。.gitignore：把编译产物、虚拟环境目录等不该进入版本库的内容提前排除，避免仓库变脏。
如果这些基础文件一开始就缺失，后面补齐通常比一开始规范更费劲。
源码、文档和测试目录怎么分工
src/：业务代码的主区域
__init__.py：让目录成为 Python 包，方便导入和组织模块。module1/、module2/：按功能拆分子模块，每个模块再继续放具体的.py文件。main.py：作为项目入口，通常放最顶层的调用逻辑。
这种拆法的重点不在“目录多”，而在于功能边界清楚。模块一旦按职责拆开，后续新增功能时不容易互相挤在同一个文件里。
docs/：给人看的说明要单独管理
conf.py：Sphinx 等文档工具的核心配置文件。index.md：文档入口页，可作为使用说明和导航起点。- 其他文档文件：可以继续补充 API 说明、部署步骤和使用教程。
把文档单独放在 docs/，比把说明零散塞进仓库各处更利于持续维护。
tests/：测试和源码保持对应关系
__init__.py：方便测试框架发现和组织测试用例。test_module1.py、test_module2.py：尽量与业务模块形成对应关系，定位问题更直接。
测试目录清晰的好处是，一旦某个模块出问题，通常可以很快找到对应测试并补齐覆盖。
为什么要单独留出 scripts 目录
scripts/ 适合存放那些需要在命令行直接执行、但又不属于主业务包内部逻辑的脚本。
script1.pyscript2.py
这类脚本常见于数据迁移、定时任务、一次性处理工具等场景。单独放置的价值在于，它们不会和 src/ 里的核心模块混在一起；当你需要重构主程序时，也更容易判断哪些脚本只是辅助用途。
结构之外，CentOS 项目还要补哪些习惯
目录规范只是起点，真正决定项目是否好维护的，往往是配套习惯有没有跟上。
- 虚拟环境：使用
virtualenv或venv隔离依赖，避免不同项目之间出现包版本冲突。 - 代码风格：遵循 PEP 8，并使用
flake8或black做检查和格式化，能减少团队协作中的风格分歧。 - CI/CD：可选择 Jenkins、Tra vis CI 或 GitHub Actions，把测试和部署流程自动化。
- 日志管理：用
logging代替print，并配置日志级别与文件回滚，排查问题时会省很多时间。
一套合理的目录结构，加上这些基本工程习惯，通常就能让 CentOS 上的 Python 项目更容易维护、扩展，也更方便他人接手。
