Python搭建局域网共享库教程

本文手把手教你用轻量级工具 pypiserver 快速搭建局域网私有 Python 包仓库，涵盖服务启动（指定包目录、禁用官方回退、配置鉴权）、客户端 pip 源配置（解决 trusted-host、HTTP 信任、认证上传等高频卡点）、以及上传后安装失败的深度排错指南——从 wheel 命名规范、大小写敏感、python_tag 兼容性到缓存清理和日志追踪，直击内网共享包时最真实、最易踩坑的每一个细节，让团队零成本拥有稳定可控的本地 PyPI 镜像。

用 pypiserver 快速启动一个可写的私有 PyPI 镜像源

局域网内共享 Python 包，pypiserver 是最轻量、最直接的选择——它不依赖数据库、不强制要求 HTTPS、支持上传和简单鉴权，适合内部团队快速搭个“包仓库”。

常见错误是直接运行 pypiserver 却没指定包目录或端口，结果服务起来但 pip install 找不到包，或者上传失败却没报错。

• 启动前先建好包存储目录：mkdir -p ~/pypi-packages
• 安装并运行（监听所有局域网 IP）：pypiserver -p 8080 --disable-fallback --authenticated update,download --passwords ./htpasswd ~/pypi-packages
• --disable-fallback 很关键：关掉对官方 PyPI 的回退，否则 pip install requests 会绕过你的镜像去下载官方版
• 密码文件用 htpasswd -sc ./htpasswd username 生成（-c 只首次加 -s 表示 bcrypt 加密）

配置 pip 指向本地镜像源（含认证与信任）

客户端不配对，服务再稳也没用。重点不是“怎么加 index-url”，而是解决三个实际卡点：HTTP 被拒绝、证书报错、上传时 401。

• 临时使用：pip install --index-url http://192.168.1.100:8080/simple/ --trusted-host 192.168.1.100 somepkg
• 永久配置写进 ~/.pip/pip.conf（Linux/macOS）或 %APPDATA%\pip\pip.ini（Windows）：

[global]
index-url = http://192.168.1.100:8080/simple/
trusted-host = 192.168.1.100
extra-index-url = https://pypi.org/simple/

pip install 仍去连 pypi.org？检查 fallback 和缓存机制

明明配了 index-url，pip install 却还是访问外网——大概率是 pypiserver 没关 fallback，或者 pip 缓存了旧的包索引元数据。

• 确认服务启动参数含 --disable-fallback，否则 pypiserver 在找不到包时自动代理到官方源
• 清空 pip 缓存：pip cache purge，尤其当之前试过失败安装时，缓存可能记住了“这个包不存在”
• 用 pip install -v xxx 看详细日志，重点找 Looking up "http://.../simple/xxx/" 这行，确认 URL 是你的内网地址
• 如果包名拼写有大小写差异（比如你传了 MyPackage-1.0-py3-none-any.whl，但 pip 查 mypackage），pypiserver 默认区分大小写，会 404

上传包后 pip install 找不到？注意文件命名与索引刷新

pypiserver 不自动扫描新增文件，也不解析 setup.py 元信息——它只按 wheel/egg 文件名里的项目名和版本做简单路由。

• wheel 文件名必须符合 PEP 427：{name}-{version}-{python_tag}-{abi_tag}-{platform_tag}.whl，例如 requests-2.31.0-py3-none-any.whl
• 上传后不要手动改文件名或挪动位置，pypiserver 启动时读一次目录，之后靠文件名匹配，不轮询
• 如果上传的是源码包（.tar.gz），确保名字是 {name}-{version}.tar.gz，且解压后顶层目录名与 name 一致
• 上传失败常见原因是权限：确保 pypiserver 进程对 ~/pypi-packages 有写权限，且 SELinux/AppArmor 没拦截（Linux 服务器上容易忽略这点）

最麻烦的其实是 wheel 文件名里那个 python_tag ——比如你用 Python 3.11 打的包，标的是 cp311，但另一台机器 pip 是 3.10，就匹配不上。这种兼容性问题不会报错，只会静默跳过，得靠 pip install -v 日志逐行盯。

以上就是《Python搭建局域网共享库教程》的详细内容，更多关于的资料请关注golang学习网公众号！