企业官网建设流程全解析

入行头两年，我的pip用法基本就一条：pip install xxx。遇到问题就百度，偶尔会用pip freeze > requirements.txt，以为自己已经会了。直到有次接到一个任务，要给一台完全断网的服务器装一套内部系统，我拿着笔记本折腾了一整天，才意识到自己连入门都算不上。后来我把pip的文档翻了个遍，又在几个项目里反复踩坑，才慢慢摸清它的完整能力边界。

这篇文章我想把这几年沉淀下来的东西整理一遍，重点讲十个平时不太被注意、但非常顶用的用法。它们不全是冷门命令，更多是"你知道但没往深处想"的那些东西。我按使用场景分成四块：本地开发、内网部署、供应链安全、性能与跨平台。无论你是刚接触Python的新手，还是已经写了几年脚本的老手，里面应该都有能直接用上的东西。

1. 开发阶段的两个高频利器：可编辑安装与requirements条件标记

先说本地开发。很多人开发自己的包时，习惯改一点代码就重新pip install .一次，装完再跑测试。这样不是不行，只是效率太低。我见过好几个人因为这个原因，觉得调试依赖包很痛苦，最后干脆把代码直接塞进site-packages里手动改，那才是真正的灾难现场。

1.1 pip install -e：改完源码立刻生效的"开发模式"

-e参数的全称是--editable，也就是可编辑安装。用法很简单：

# 在项目根目录（有pyproject.toml或setup.py的地方）执行 pip install -e .

装完之后，这个包不会把源码复制到site-packages里，而是建立一个指向你源码目录的链接。Python在import的时候，会直接读取你当前工作区的源码文件。所以你在项目里改了代码，不需要重新安装，立刻就能生效。

这个模式最适合三种场景：

• 你正在开发一个库，同时有另一个项目在依赖它。你不想每次改库都要重新装一遍。
• 你想调试第三方依赖包。先把它的源码clone下来，然后pip install -e这个源码目录。
• 你想确认某个分支的改动效果，又不想污染环境。可编辑安装配合虚拟环境非常顺手。

原理上，这套机制在PEP 660之后统一了实现方式，pip会调用项目的构建后端生成一个"可编辑安装包"，然后通过__editable__文件或pth文件把源码目录注册到Python的搜索路径里。对于纯Python代码来说，改动即时生效；但对于包含C扩展的项目，编译产物不会自动重建，你需要手动重新执行一次构建，这个很容易忽略。

有个经典坑我必须提醒你：pip install -e在开发机上是神器，但千万别在Docker镜像或者生产环境里用。容器构建是一次性的，可编辑安装wiring的是容器外的源码路径，一旦镜像被复制到别处，这个链接就断了。生产环境里老老实实用普通安装。

1.2 requirements文件：条件标记和依赖分组的高级写法

requirements.txt本身大家都会写，但大多数人只用了它最基础的"一行一个包"功能。其实这个文件支持环境条件标记、本地路径引用、可编辑安装、约束文件引用，组合起来能解决很多实际的依赖管理问题。

举个我实际用过的结构，一个稍微复杂点的项目可以这样组织：

# requirements.txt（基础运行依赖） fastapi==0.109.2 uvicorn[standard]==0.27.1 sqlalchemy>=2.0,<2.1 redis>=4.5,<6.0 # requirements-dev.txt（开发环境依赖） -r requirements.txt pytest>=7.0 ; python_version >= "3.8" ruff==0.3.0 ; sys_platform == "linux" -e .[dev,test]

注意最后一行-e .[dev,test]，它包含两层意思：一是以可编辑方式安装当前项目，二是安装pyproject.toml里定义的两个extra分组。这样你在不同环境只要切换requirements-dev.txt和requirements.txt，就能保持一致。

条件标记; python_version >= "3.8"这类写法，是很多人的知识盲区。它的作用是：同一份requirements文件，在不同Python版本或操作系统上，pip会自动过滤掉不匹配的行。比如pytest在Python 3.8以下不放进来，ruff只在Linux上装。这在维护多Python版本、跨平台项目时非常有用。

另外一个被低估的功能是通过路径引用本地包：

# 本地私有包，不发布到PyPI ./vendor/my-common-lib

配合-e可以直接指向本地待开发版本。这个在微服务拆分时特别好用，几个服务共享一个公共库，还没到发布版本的时候，直接路径引用就行。

用requirements文件踩过最疼的一个坑是：条件标记不是万能的。pip解析时按当前解释器环境来过滤行，但你无法用它表达"Python 3.8以上用A版本，以下用B版本"这种复杂逻辑。真要复杂到那个程度，就该上pip-tools的pip-compile了，它能用约束输入生成锁定清单，条件标记也会正确编译进结果。我的建议是：小项目手写，项目规模上了三个以上微服务，尽早引入编译锁文件。

2. 内网部署与离线分发：源配置、离线下载和目标目录三件套

没有经历过断网环境的人，很难理解为什么pip能"离线安装"也算高级用法。直到你面对一台物理隔离的服务器、或者一条网络极差的生产链路，才会意识到平时随手pip install有多方便。内网部署这块，我总结成三个互相配合的招：源配置、离线下载、指定安装目录。

2.1 私源配置与双源使用：--index-url、--extra-index-url与trusted-host

私有源这个问题，几乎所有中大型团队都会遇到。互联网上的Python源在大陆地区访问速度不稳定，加上很多公司有内部包不能外泄，必须自建或使用镜像源。基础命令大家都会：

pip install requests -i https://mirrors.example.com/simple

但每次敲-i太累，更好的做法是写进配置。pip的配置文件在Linux/macOS上是~/.config/pip/pip.conf，Windows上是%APPDATA%\pip\pip.ini：

[global] index-url = https://mirrors.example.com/simple trusted-host = mirrors.example.com timeout = 60

trusted-host很多人不理解。它用来声明哪些主机可以被信任，主要应对自建源只走HTTP、没有HTTPS证书的情况。不加它，pip会拒绝连接非HTTPS源。加了之后，pip会允许对该主机使用HTTP。这里有个安全取舍：如果在内网环境，问题不大；如果在公网，除非源是你自己可控的，否则慎用。

还有两个容易搞混的参数：--index-url和--extra-index-url。前者是替换默认源，后者是在默认源之外增加一个查询源。看起来差不多，实际行为差远了：

我用--extra-index-url踩过一个大坑：两个源上存在同一个包的不同版本时，pip不会智能合并，它会分别去两边找，常常出现"下载了包A，但依赖的包B找不到"或者版本错乱的问题。更诡异的是，某些源返回的元数据不完整，会导致本来能装的包莫名报"找不到版本"。所以我的建议是：能用单一--index-url就别用双源；实在要双源，把公共包和私有包拆开放在不同的requirements文件里分开安装。

2.2 pip download：为一台断网机器准备整个依赖仓库

这是离线部署的核心。在一台能联网的机器上，先用pip download把需要的包全部拉下来，然后拷贝到断网机器上，用本地文件安装。基本流程：

# 在联网机上下载全部依赖到offline_packages目录 pip download -r requirements.txt -d offline_packages/ # 拷贝offline_packages到目标机器后，离线安装 pip install --no-index --find-links=offline_packages/ -r requirements.txt

参数解释一下：--no-index告诉pip不要访问任何源，--find-links指定从本地目录找包。这样整个安装过程完全不碰网络。

但真正值钱的是跨平台下载。假设你联网机器是macOS，目标机器是Linux，你不能直接把macOS下的whl文件装到Linux上。你需要用平台参数，强制pip下载指定平台的wheel：

# 为Linux x86_64 + Python 3.11 下载 pip download -r requirements.txt -d linux_packages/ \ --platform manylinux2014_x86_64 \ --python-version 3.11 \ --implementation cp \ --only-binary=:all:

这里--only-binary=:all:是关键。它让pip只下载wheel格式的包，不要源码包。因为源码包（sdist）到你手里还得现场编译，断网机器上没有编译环境的话就是个死局。加了这个参数，pip如果在指定平台上找不到对应wheel，就会直接报错，而不是默默丢给你一个源码包让你去编译。

另外建议下载完做个完整性校验，把所有文件的sha256算一遍记录到校验文件里。别嫌麻烦，拷贝过程出现文件损坏的概率比你想的高。这个校验和第3章哈希校验可以联动。

2.3 pip install --target：把依赖直接装进指定目录

--target参数让我在一段时间里直呼"怎么没早知道"。它的作用是指定安装目录，而不是默认的site-packages。典型场景是：没有虚拟环境可以用、需要把依赖和代码打进同一个部署包、或者做无服务器函数部署时，函数运行时会从你的函数代码目录里找依赖。

pip install --target ./deploy_libs flask==3.0.0 # 运行代码前设置PYTHONPATH export PYTHONPATH=$(pwd)/deploy_libs:$PYTHONPATH

这个参数有个反直觉的地方：它不会把包装成普通目录结构，而是会创建类似deploy_libs/flask的文件夹，照样可以通过import flask导入。同时，pip会把依赖的依赖也一并装进来，所以最终目录里会有一大堆包。

使用时有几个注意点：

• 安装目录里如果已经有同名包，旧版本不会自动清理，容易残留。我从不用它做增量升级，要升级就清空目录重装。
• 卸载很麻烦，没有uninstall --target这种干净操作，只能手动删目录。
• 如果你只需要特定包、想控制依赖范围，可以加--no-deps，然后手动逐个装依赖。

我在一个比较老的项目里用过这个方案，那个项目没有虚拟环境，系统Python不允许乱动全局环境，部署脚本强制要求"代码+依赖一个目录"。--target加--no-deps加手动依赖清单，虽然丑，但稳。

3. 供应链安全与版本基线：哈希校验、约束文件与VCS安装

很多人的依赖管理停留在"能跑就行"，但一旦进入生产环境、或者要交付给客户，依赖的可信性和可复现性就变成大事。我经历过一次内部包被篡改之后，才对哈希校验彻底重视起来。

3.1 --require-hashes：把requirements变成带签名的清单

--require-hashes是一个安全开关，要求requirements文件里的每个安装包都必须附带sha256哈希值。pip在安装时会校验下载包的实际哈希，不一致就拒绝安装。

一个带哈希的requirements文件长这样：

flask==3.0.0 --hash=sha256:7f9a6c8f91e55a4de6b7efd6a8d6c1a7b6e521e9f4c4a2c1d6e76b6f7c3a6b8d requests==2.31.0 --hash=sha256:9b47d3f5a6f8d1e2d81e9d0e0b2d4f526b4c5b9e742e6f3a2d31e4b5f7c4f5a2e

生成哈希有两个途径：一是pip hash命令针对单个文件计算，二是用pip-tools的pip-compile --generate-hashes生成整个锁文件。后者在真实项目里更实用。

--require-hashes的状态下有几个硬性限制，必须知道：

• 不能用-e可编辑安装。
• 不能用版本范围（比如flask>=3.0），所有包必须锁定精确版本。
• 间接依赖也必须出现在requirements里并且有哈希，不能靠pip自动解析。也就是说，你必须在清单里列出完整依赖树。

第三点是很多人失败的原因。平时你只写顶层依赖，pip会自动带上间接依赖；开了--require-hashes，它要求清单里能看到的每个包都有哈希，间接依赖一旦没有被锁定，pip会直接报错。所以项目里真要启用，几乎必然要引入锁文件工具，手工维护是不现实的。

3.2 constraints.txt：统一多个项目的版本"天花板"

constraints.txt是一个概念上很像requirements、行为上却完全不同的文件。它的作用是：只约束版本，不触发安装。也就是说，你可以在一个单独的约束文件里写死某些包的版本上限，然后在多个项目里通过-c constraints.txt引用它，让所有项目共用同一套版本基线。

pip install -r requirements.txt -c constraints.txt

约束文件内容的写法与requirements类似：

# constraints.txt # 只限制版本，不负责安装这些包 requests>=2.20,<3.0 cryptography>=41.0

它的价值在微服务架构里特别明显。假设你有五个服务，每个服务的requirements里都有requests，版本各不相同。某天安全通告说某版本以下的requests有个漏洞，你需要立刻把所有服务的requests都提到安全版本。如果没有约束文件，你得改五个项目的requirements；有了它，只改一个constraints文件就够了。

要注意的是：约束里的版本如果和requirements里的显式声明发生冲突，pip会报错，而不是默默忽略。这是个保护机制，防止你以为约束生效了、实际装了个计划外的版本。所以把约束文件引入已有项目时，第一件事就是对每个服务跑一遍pip install --dry-run -c constraints.txt -r requirements.txt，提前找出冲突。

3.3 VCS直装：直接从Git仓库拉代码安装包

pip支持直接从Git、Mercurial等版本控制仓库安装Python包。这在依赖尚未发布到PyPI、或者需要直接从私有仓库拉取某个分支的代码时非常实用。

# 直接从Git安装，指定分支或tag pip install "git+https://examples.com/company/internal-lib.git@main#egg=internal-lib" # 指定commit，保证可复现 pip install "git+https://examples.com/company/internal-lib.git@a1b2c3d4ef567890abcdef#egg=internal-lib" # monorepo里只装子目录 pip install "git+https://examples.com/company/monorepo.git@main#subdirectory=python-packages/internal-lib&egg=internal-lib"

这里的#egg=internal-lib用来告诉pip这个项目的发行名称。modern pip对egg的要求宽松了一些，但我建议还是写上，尤其在monorepo里，不写它pip可能不知道该怎么命名项目。指定commit而不是分支，这是我从生产事故里学到的一条铁律：分支会动，commit永不变。用@main今天装的和明天装的可能是不同代码，排查问题时会疯掉。

VCS安装时还有个问题：pip会把整个仓库clone下来，再执行构建。仓库大、历史深，clone会非常慢。可以在clone前做浅克隆吗？很遗憾，pip本身不暴露这个选项。我的做法是：先用git clone --depth 1手动把仓库拉到本地指定commit，然后从本地路径安装。

4. 性能、缓存与跨平台兼容：从wheel构建到精确下载

最后这块偏"调优"性质。它不会让功能发生变化，但能让构建时间变短、让部署包变小、让跨平台的坑变少。都是一些平时注意不到、到关键时刻能救命的细节。

4.1 pip cache：缓存查看、清理与CI环境里的禁用策略

pip从20.1版本开始内置了缓存管理。每次安装下载的wheel和HTTP响应都会被缓存，下一次安装相同版本时就直接从缓存读取，不再走网络。这在反复重建环境、或者频繁在虚拟环境间切换时能省大量时间。

常用命令：

# 查看缓存占用 pip cache info # 列出缓存的wheel pip cache list # 删除特定包的所有缓存 pip cache remove numpy # 清空全部缓存 pip cache purge

缓存带来便利的同时也埋过一个坑：本地开发一个包，版本号一直没变，但源码改了，重新pip wheel生成同名wheel时，pip可能会从缓存里取出旧的那份，导致你构建了半天还是旧代码。所以只要涉及本地构建，我习惯加--no-cache-dir，从源头绕开这个问题。

CI环境里另一个常见问题：缓存越积越大，把构建机的磁盘塞满。现在很多流水线的镜像每次都是新拉的，缓存意义不大，反而拖慢首次构建。我的建议是在CI里设置PIP_NO_CACHE_DIR=1，明确禁用缓存，让每次构建都干干净净。

4.2 pip wheel：把源码编译问题一次性解决在构建机上

pip wheel和pip download很容易被混淆。简单说，download是下载现成的包，wheel是"下载+构建"：它会下载源码包或wheel，然后本地构建成wheel文件，输出到指定目录。

pip wheel -r requirements.txt -w wheelhouse/

为什么需要这个？有些包在PyPI上没有当前平台对应的预编译wheel，比如某些C扩展库，你必须现场编译。pip install的时候也能编译，但那是边装边编，一旦编译失败你就得去排查整个环境。用pip wheel，你可以在构建机上把能编译的全部编译成wheel，形成一套完整的offline wheelhouse，之后在目标机器上用--find-links安装，就完全不需要编译工具链了。

我之前处理过一个离线环境，目标机器上是精简系统，连gcc都没有。我就是在联网机器上跑pip wheel -r requirements.txt -w wheelhouse/ --no-cache-dir，把一堆源码包全部编译成wheel，然后拷贝过去离线安装。从那以后，"离线部署"和"必须现场编译"这两件事就彻底解耦了。

4.3 --only-binary与平台指定下载：用对标签才能跨平台

--only-binary=:all:在第2章出现过，这里专门讲讲它和平台参数的配合边界。wheel文件有一套规范化的命名标签，比如numpy-1.26.4-cp311-cp311-manylinux_2_17_x86_64.whl，里面编码了Python版本（cp311）、ABI、平台（manylinux_2_17_x86_64）等信息。pip正是靠这些标签决定是否能安装某个wheel。

跨平台下载时，你需要告诉pip"我要的是哪个平台哪个Python版本的包"。常用的组合参数：

# 下载Windows平台、Python 3.12、64位的wheel pip download numpy -d win_packages/ \ --platform win_amd64 \ --python-version 3.12 \ --implementation cp \ --only-binary=:all: # 下载macOS Apple Silicon平台 pip download numpy -d mac_packages/ \ --platform macosx_11_0_arm64 \ --python-version 3.11 \ --implementation cp \ --only-binary=:all:

用这套参数有两条铁律：

• 纯Python包不受平台限制，标签是py3-none-any，任何平台都能装。所以下载时可以不加平台参数，或者加了也无所谓。
• 带C扩展的包必须严格匹配平台和ABI。cp311的包不能装在cp312上，manylinux和musllinux（Alpine Linux）是两套不同的平台标识，不能混用。

想知道当前环境支持哪些标签，直接跑pip debug --verbose，它会列出大量支持的tag信息。我在处理跨平台问题时经常拿它对照，比你一个一个搜文档快得多。注意，这套跨平台指定下载只适用于pip download和pip wheel，不要尝试直接把下载的包用在当前环境安装，你需要把文件传到目标平台再装。

最后分享一条我个人的操作习惯：新项目起步时，我会先列顶层依赖，用pip-compile生成锁文件，并在CI里跑--require-hashes校验；如果要交付离线环境，构建机上提前做一套wheelhouse；本地开发则统一用虚拟环境加pip install -e。这套流程跑顺之后，依赖问题很少再来找我。pip的文档其实写得很好，只是平时没人愿意翻。如果你今天只记住一条，那就记住这句：能用虚拟环境别直接装，能锁版本就别漂移，能提前准备wheel屋就别到现场编译。