Python项目结构、打包与发布入门：venv、requirements、pip 与项目组织

学到这里，你已经能写函数、类、模块、网络请求、数据处理，甚至开始接触数据库和并发。

但当代码从“一个脚本”逐渐长成“一个项目”时，你很快会遇到新的问题：

  • 代码应该怎么分目录？
  • 依赖怎么管理？
  • 不同机器上如何保证环境一致？
  • 项目怎么安装和运行？
  • 写给自己看的脚本，怎么变成别人也能复用的项目？

这就是“项目结构、打包与发布”这一部分要解决的核心问题。

很多初学者刚开始写 Python 时，所有内容都堆在一个文件里，这在入门阶段没问题。但一旦代码量变大，就会出现：

  • 文件越来越长；
  • 模块边界越来越乱；
  • 依赖不清晰；
  • 别人拿到代码跑不起来；
  • 自己过一段时间也看不懂。

所以，真正想把 Python 用到工程实践中，一个很重要的转折点就是：

从“会写代码”，逐渐过渡到“会组织项目”。

本文会围绕下面几个主题展开：

  • 虚拟环境为什么重要；
  • pip 和依赖管理；
  • requirements.txt 的作用；
  • 一个常见的 Python 项目目录应该怎么组织；
  • 脚本项目和包项目有什么区别；
  • 初学阶段该建立哪些项目习惯。

一、为什么项目结构这么重要？

一个小脚本当然可以只有一个文件。

但项目一旦变大，就会自然出现这些内容：

  • 业务代码；
  • 配置文件；
  • 测试代码；
  • 数据文件；
  • 日志目录；
  • 第三方依赖；
  • 启动入口。

如果没有结构，后面就很容易：

  • 模块互相乱引用；
  • 环境混乱；
  • 路径到处写死；
  • 迁移和协作都变困难。

所以项目结构的意义不是“形式主义”，而是：

让代码更容易维护、复用、协作和部署。

二、虚拟环境：为什么不要把依赖全装到系统里？

2.1 依赖冲突是非常真实的问题

假设你有两个项目：

  • A 项目需要 requests==2.28；
  • B 项目需要 requests==2.31。

如果都装在同一个全局环境里，就很容易互相影响。

这就是虚拟环境存在的意义：

给每个项目隔离出一套自己的 Python 依赖环境。

2.2 创建虚拟环境
1
python -m venv .venv

这会创建一个 .venv 目录。

2.3 激活虚拟环境

Linux / macOS：

1
source .venv/bin/activate

Windows：

1
.venv\Scripts\activate

激活后再安装依赖，通常就只会影响当前项目环境。

2.4 为什么建议目录名常用 .venv？

因为这是很常见、很清晰的命名方式，很多编辑器也能自动识别。

三、pip：安装和管理依赖的基础工具

3.1 安装第三方库
1
pip install requests
3.2 指定版本安装
1
pip install requests==2.31.0

指定版本的意义在于：

  • 更可控；
  • 更容易复现环境；
  • 避免因为依赖升级导致行为变化。
3.3 查看当前环境依赖
1
pip list
3.4 导出依赖列表
1
pip freeze > requirements.txt

这在项目交付和环境迁移时非常常见。

四、requirements.txt：为什么它几乎是基础配置

4.1 它解决什么问题？

当别人拿到你的项目时，最常见的问题之一是：

这个项目到底依赖哪些库？

这时 requirements.txt 就是最简单、最传统的答案。

例如：

1
2
3
4
requests==2.31.0
beautifulsoup4==4.12.3
pandas==2.2.2
openpyxl==3.1.5
4.2 从依赖文件安装
1
pip install -r requirements.txt

这样别人就能快速还原依赖环境。

4.3 为什么它重要？

因为它提升了：

  • 可复现性；
  • 可协作性；
  • 可部署性。

如果没有依赖清单，很多项目“在你电脑上能跑”，但别人一拿就不行。

五、一个常见的 Python 项目结构长什么样？

初学阶段不需要把结构设计得特别复杂，但可以先建立一个比较健康的基本形态。

例如：

1
2
3
4
5
6
7
8
9
10
11
12
my_project/
├── .venv/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── services.py
│   └── utils.py
├── tests/
│   └── test_main.py
├── data/
├── requirements.txt
└── .gitignore
5.1 各目录可以怎么理解？
  • app/：核心业务代码；
  • tests/：测试代码；
  • data/：样例数据或临时数据；
  • requirements.txt：依赖清单；
  • .gitignore：忽略不该提交的文件；
  • .venv/：虚拟环境目录。
5.2 为什么不要把所有代码都堆在根目录？

因为随着文件变多，很容易混乱。

把核心代码集中到 app/ 或类似目录里，通常会更清晰。

六、模块拆分：什么时候应该分文件？

初学者常见问题之一是：

  • 一个文件写到几百行、上千行；
  • 所有函数、类、配置、入口全放一起。

这在小脚本阶段可以忍，但项目一大就很难维护。

6.1 比较自然的拆分方式

可以按职责拆：

  • main.py：程序入口；
  • config.py：配置处理；
  • models.py：数据结构；
  • services.py：核心业务逻辑；
  • utils.py：通用工具函数。
6.2 一个重要原则

拆分不是为了文件越多越高级，而是为了职责更清晰。

如果拆得过细，也会反而增加理解成本。

七、脚本项目与包项目：先理解区别

7.1 脚本项目

脚本项目通常更偏：

  • 一个或几个 .py 文件；
  • 直接运行；
  • 解决某个具体任务。

例如：

  • 数据清洗脚本；
  • 文件批处理脚本；
  • 小型采集工具。
7.2 包项目

包项目更偏：

  • 可复用模块集合；
  • 可以被别人 import；
  • 结构更规范；
  • 更适合长期维护。

也就是说：

  • 写给自己一次性用的小工具，更像脚本；
  • 想长期维护、复用、发布的，更应该按包来组织。

八、入口文件与 if __name__ == '__main__'

在项目里，经常会有一个“启动入口”。

例如：

1
2
3
4
5
6
def main():
    print('程序启动')


if __name__ == '__main__':
    main()

这段结构的意义在于：

  • 直接运行这个文件时会执行；
  • 被别的模块导入时不会自动运行主流程。

这是组织脚本入口的一个基础习惯。

九、配置和数据不要硬编码到代码里

项目一变大，另一个常见问题就是：

  • 文件路径写死；
  • 数据库地址写死；
  • 账号密码写死；
  • 端口号写死。

这会导致代码很难迁移和复用。

更好的方式是逐步把这些内容从业务逻辑里分离出来，例如：

  • 放到配置文件；
  • 放到环境变量；
  • 通过命令行参数传入。

初学阶段你至少要先形成意识：

配置和代码最好分开。

十、.gitignore：哪些内容不该提交？

当你开始用 Git 管理 Python 项目时，通常不应该把下面这些东西提交进仓库：

  • 虚拟环境目录；
  • 缓存文件；
  • 临时日志；
  • 编译产物；
  • 本地数据库文件；
  • 编辑器配置缓存。

一个基础的 .gitignore 可能会包含：

1
2
3
4
5
.venv/
__pycache__/
*.pyc
.env
*.log

这不是 Python 语言本身的知识，但却是项目实践中非常基础的一部分。

十一、一个小型项目组织示例

假设你要写一个“批量请求网页标题并保存结果”的项目，可以像这样组织：

1
2
3
4
5
6
7
8
9
10
11
page_title_tool/
├── .venv/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── fetcher.py
│   └── exporter.py
├── tests/
│   └── test_fetcher.py
├── requirements.txt
└── .gitignore

其中：

  • fetcher.py 负责请求网页；
  • exporter.py 负责导出 CSV；
  • main.py 负责串起整个流程；
  • tests/ 负责测试。

这就是“项目结构服务于职责清晰”的一个直观例子。

十二、学习项目结构时的常见误区

12.1 不要一上来照搬特别复杂的大项目结构

很多开源项目结构非常复杂，那是因为：

  • 规模大；
  • 生命周期长；
  • 团队协作复杂；
  • 发布要求高。

初学阶段没必要机械照搬。

12.2 不要把“能跑”当成“组织得好”

代码能运行只是第一步。

一个项目是否健康，还要看：

  • 模块边界是否清晰；
  • 依赖是否可复现；
  • 目录是否容易理解；
  • 别人能否快速上手。
12.3 不要忽视环境隔离

虚拟环境看起来不起眼，但它真的能帮你省下很多莫名其妙的环境问题。

12.4 不要过度拆分

文件拆太碎、层级太多，也会让项目难懂。

所以还是那句话：

结构是为了清晰，而不是为了显得高级。

十三、学习建议：这一章最值得优先掌握什么？

13.1 先把虚拟环境和依赖管理养成习惯

这是最实用、最该尽早养成的工程习惯之一。

13.2 先学会把代码分目录、分模块

哪怕只是简单分成：

  • 核心代码；
  • 测试代码；
  • 数据目录；

都会比全堆一起更清晰。

13.3 先理解脚本和项目的区别

这会帮助你决定：

  • 我现在是在写一次性工具；
  • 还是在写一个长期维护的项目。
13.4 后续再学习更现代的打包方式

当你继续深入时，还会接触：

  • pyproject.toml
  • setuptools
  • poetry
  • 构建和发布到包仓库

但在入门阶段，先把虚拟环境、pip、requirements.txt 和目录结构掌握好就很够用了。

十四、总结

这一篇我们系统梳理了 Python 中“项目结构、打包与发布入门”的核心内容：

  1. 为什么项目结构重要：理解工程化组织对可维护性的意义；
  2. 虚拟环境：学会隔离项目依赖；
  3. pip 与依赖管理：掌握安装、查看和冻结依赖；
  4. requirements.txt：帮助项目环境可复现；
  5. 常见项目目录结构：学会按职责组织代码；
  6. 模块拆分：让代码职责更清晰；
  7. 脚本项目与包项目：理解一次性工具和长期项目的区别；
  8. 入口文件与配置管理：学会更规范地组织程序启动和环境参数；
  9. .gitignore：理解哪些文件不应纳入版本管理。

如果说前面的章节是在学习“怎么把功能写出来”，那么这一篇更像是在回答：

当代码不再只是一个脚本，而开始变成真正的项目时，应该怎样让它更清晰、更稳定、更适合协作？

掌握这一篇之后，你的 Python 学习就已经不再只是语言层面，而开始进入工程实践层面了。

继续往后写时，比较自然的衔接方向通常有两个：

  • Python学习路线总结与实战建议：把整个系列收束起来；
  • Python Web 开发入门：进入更完整的后端工程实践。

参考资料