直接换国内镜像源并设置--default-timeout=120可解决pip的readtimeouterror，因该错误本质是响应读取超时而非连接失败，仅换源或仅调timeout均无效。

直接换国内镜像源 + 调高 --default-timeout 就能解决，不用重装 pip 或折腾系统网络设置。

为什么只换源或只加 timeout 都可能失败

pip 的 ReadTimeoutError 本质不是“连不上”，而是“连上了但某个 chunk 卡住超过默认 15 秒”。官方源（pypi.org）对国内 IP 存在速率限制和高丢包率，哪怕你网络正常，也可能在下载 torch、tensorflow 这类大包时反复卡在中间某次响应读取上。

• 只换源（如加 -i https://pypi.tuna.tsinghua.edu.cn/simple）能提速，但若本地网络偶发抖动、DNS 解析慢、或 CDN 缓存未命中，仍会触发 timeout
• 只加 --timeout=60 没用——这个参数只控制 TCP 连接建立时间，不覆盖后续的响应读取；必须用 --default-timeout
• 不配 trusted-host 会导致 HTTPS 验证失败，错误信息可能被吞掉，表现为静默退出或 fallback 到官方源再超时

临时安装：单次命令就生效

适合调试、CI/CD 流水线或不确定是否要永久改配置的场景。参数顺序不能错：--default-timeout 必须紧接在 pip install 后、包名前。

TikTok Creator Pipeline

TikHub API 多平台数据爬取工具，支持抖音/TikTok/B站等。用户提及以下需求时调用：1) 爬取视频或评论；2) 获取用户信息/粉丝列表；3) 批量下载无水印视频；4) 抖音链接转文字（下载→音频→Whisper pipeline）；5) 调用 TikHubAPI。

下载

• 正确写法：pip install --default-timeout=120 -i https://pypi.tuna.tsinghua.edu.cn/simple requests
• 错误写法：pip install requests --default-timeout=120 -i ...（报 unrecognized arguments）
• 清华源在教育网和多数家用宽带下最稳；阿里云源在部分企业网更可靠；中科大源适合科研单位
• 如果还失败，加 --retries 5 让 pip 多试几次，对偶发性丢包很关键

永久配置：避免每次敲一长串参数

配置文件路径和格式极易出错，Windows 和 macOS/Linux 完全不同，且文件名、扩展名、段落格式都敏感。

• Windows：在 %APPDATA%\pip\pip.ini 中写入（注意是 .ini，不是 .conf 或 .txt）
• macOS/Linux：在 $HOME/.pip/pip.conf 中写入（目录需手动创建）
• 内容必须严格为三行，无空行、无多余空格：

  [global]
  index-url = https://pypi.tuna.tsinghua.edu.cn/simple
  default-timeout = 120
  trusted-host = pypi.tuna.tsinghua.edu.cn

• 改完后运行 pip config list 确认生效；若无效，大概率是路径错、文件名错、或权限不足（Linux/macOS 下检查 .pip 目录权限）

CI/CD 或内网环境的特殊处理

GitHub Actions、GitLab CI 等环境 DNS 不稳、出口 IP 易被限频，单纯换源+调 timeout 不够。

• 务必用环境变量 PIP_INDEX_URL 和 PIP_DEFAULT_TIMEOUT，比命令行参数更可靠（不会被 workflow 其他步骤覆盖）
• 加 --no-cache-dir：CI 容器本就不该复用 pip 缓存，缓存损坏会导致静默失败
• 公司内网有代理？必须显式传 --proxy http://user:pass@host:port，pip 不读系统代理设置
• 私有源（如 Nexus）要确认支持 /simple/ 路径，且允许匿名 GET；否则 pip 会 fallback 到官方源再超时

最容易被忽略的是：timeout 值设得太大（比如 600），真断网时 pip 会白等 10 分钟才报错；设得太小（比如 30），torch 这种包依然会失败。60–120 是国内镜像源下的经验安全区间，超出这个范围还失败，问题大概率不在 timeout 本身。