docs(guides): 补上验 sdist 那条命令的完整形状,以及漏掉 --no-build-isolation 的坑

第八步原来只说「sdist 要单独取,加 --no-binary :all:」,没给完整命令。照着上一条 pip
download 拼出来的那条**跑不通**,这是发 1.0.2 时实测撞上的。

原因是 --no-binary :all: 让 pip 取 sdist 之后会去构建它的元数据,而构建要先装
build-system.requires 里那个 setuptools——而 --index-url 已经把索引整个换成了这个 registry,
那儿只有 polyloop。报出来的是「Failed to build 'polyloop' when installing build
dependencies」,读起来像刚传上去的包坏了,实际上包好好的、坏的是命令的索引配置。这个失败
形态指向错误的方向,所以值得单独记一段。

--no-build-isolation 用当前 conda 环境里已经装着的 setuptools(dev 那组的 build 带着它),
不去索引找。跳过构建隔离不影响这一步的判据:这里验的是 registry 上那份 sdist 的内容,不是
「下游能不能从源码构建它」——真要验后者,索引那一项得写成 --extra-index-url。

补进去的命令逐字实测过,PKG-INFO 9566 字符,与文档里写的数字一致。
This commit is contained in:
2026-08-27 05:44:54 -04:00
parent d833b7a4d9
commit 72cfba5996
+23 -2
View File
@@ -305,13 +305,34 @@ unzip -p polyloop-X.Y.Z-py3-none-any.whl polyloop/__init__.py | grep __version__
之间没有任何机器约束——构建时工作区不干净、`dist/` 没清、传错了文件,都会让一个「下载成功」 之间没有任何机器约束——构建时工作区不干净、`dist/` 没清、传错了文件,都会让一个「下载成功」
的包里装着旧代码。 的包里装着旧代码。
sdist 要单独取,加 `--no-binary :all:`。它里面那份 `PKG-INFO` 的正文就是包页面要渲染的 sdist 要单独取。它里面那份 `PKG-INFO` 的正文就是包页面要渲染的 README,可以在这里先看一眼
README,可以在这里先看一眼1.0.1 那次是 6462 个字符): 1.0.1 那次是 6462 个字符1.0.2 是 9566 个):
``` ```
NO_PROXY=gitea.iomgaa.online PYTHONUNBUFFERED=1 conda run --live-stream -n PolyLoop \
pip download --no-deps --no-binary :all: --no-build-isolation \
--index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
"polyloop==X.Y.Z"
tar -xzf polyloop-X.Y.Z.tar.gz -O polyloop-X.Y.Z/PKG-INFO | head -40 tar -xzf polyloop-X.Y.Z.tar.gz -O polyloop-X.Y.Z/PKG-INFO | head -40
``` ```
**`--no-build-isolation` 不能省,而漏了它的失败形态会指向错误的方向。** `--no-binary :all:`
让 pip 取 sdist 而不是 wheel,而 pip 拿到 sdist 之后会去构建它的元数据,构建要先装
`pyproject.toml``build-system.requires` 那个 setuptools——`--index-url` 已经把索引整个换成
了这个 registry,那儿只有 polyloop,没有 setuptools。报出来的是:
```
ERROR: Failed to build 'polyloop' when installing build dependencies for polyloop
```
这句话读起来像刚传上去的那个包坏了,而实际上包好好的,坏的是这条命令的索引配置。
`--no-build-isolation` 让 pip 用当前 conda 环境里已经装着的 setuptools`dev` 那组的 `build`
带着它),不去索引找。
跳过构建隔离不影响这一步的判据:这里验的是 registry 上那份 sdist 的**内容**对不对,不是
「下游能不能从源码把它构建出来」。真要验后者,索引那一项得写成 `--extra-index-url`,让 PyPI
仍然在链上。
这一步单独占一个位置,而不是并进第七步说一句「传完了」,是因为 PolyGateway 那两个缺失版本 这一步单独占一个位置,而不是并进第七步说一句「传完了」,是因为 PolyGateway 那两个缺失版本
的形态就是「本地看起来全做完了」——只有一条真的去 registry 取一次的命令能区分开。 的形态就是「本地看起来全做完了」——只有一条真的去 registry 取一次的命令能区分开。