一、为什么需要pip install -e .？它和普通安装的区别 #

-e/--editable是开发模式安装，核心价值在于：Python不会把项目代码复制到环境的site-packages目录，而是在site-packages里创建一个符号链接（或.pth文件）指向你本地的Git仓库代码。这样你修改本地repo里的代码后，不用重新安装就能直接生效——这对调试、开发项目本身非常方便。

如果你的目标只是使用这个项目（而非参与开发），完全不需要-e，直接运行pip install .就足够：它会自动读取pyproject.toml，安装所有依赖，并且把项目代码打包后安装到你的Python环境里。

总结差异：

• pip install -e .：开发模式，本地代码修改实时生效，适合项目开发者
• pip install .：普通安装，代码被复制到site-packages，适合普通用户使用项目

二、pip install -e .是不是读取了pyproject.toml？ #

完全正确！pyproject.toml是现在Python打包的标准配置入口，所有现代工具（包括pip、setuptools）都会优先读取它：

• 它定义了项目的运行依赖（dependencies字段）
• 构建系统的要求（build-system字段，比如你这里的setuptools>=61.0）
• 包的查找规则（tool.setuptools.packages.find字段，比如指定从src目录找包）

你看到的Installing build dependencies日志，就是pip根据pyproject.toml里的build-system.requires字段，自动下载安装构建项目需要的工具。

三、手动提取依赖做requirements.txt，和pip install -e .效果一样吗？ #

不一样，核心差异有两点：

1. pip install -e .不仅安装依赖，还会把你的项目以可编辑模式注册到Python环境；而只运行pip install -r requirements.txt只会安装依赖，你的项目代码不会被Python识别为已安装的包（直接import会报错）。
2. 手动提取依赖很容易遗漏构建依赖（比如你pyproject.toml里的setuptools>=61.0），而pip install -e .会自动处理这些构建需要的工具。

如果想实现非编辑模式的完整安装，直接运行pip install .即可，它会自动解析pyproject.toml的所有配置，不需要手动处理依赖。

四、最简便的离线打包方案（获取所有whl文件） #

针对你的离线安装需求，这里提供两种最直接的实现方式：

方法1：用pip download一键下载所有需要的包 #

这是最高效的方式，pip download会自动读取pyproject.toml的配置，下载所有构建依赖、运行依赖，甚至项目本身的包到指定目录：

1. 进入Git项目的根目录（有pyproject.toml的文件夹）
2. 运行命令：

pip download --dest ./offline_packages .

• --dest ./offline_packages：指定所有包保存到当前目录下的offline_packages文件夹
• .：表示当前项目，pip会自动解析pyproject.toml里的所有依赖

运行完成后，offline_packages里会有所有需要的.whl文件（少数项目可能生成.tar.gz源码包，但大部分现代项目都支持whl）。

离线安装步骤：

1. 把offline_packages文件夹复制到离线机器
2. 若离线机器有项目代码，进入项目根目录运行：

pip install --no-index --find-links ./offline_packages .

• --no-index：禁止从PyPI下载任何包
• --find-links ./offline_packages：从指定目录查找本地包

3. 若没有项目代码，直接安装项目的whl包（如果offline_packages里存在）：

pip install --no-index --find-links ./offline_packages ./offline_packages/your_project_name-*.whl

方法2：先生成完整的requirements.txt再下载 #

如果你需要先明确看到所有依赖，可以用pip-tools生成包含所有依赖（包括构建依赖）的requirements.txt，再下载：

1. 安装pip-tools：

pip install pip-tools

2. 从pyproject.toml生成requirements.txt：

# 生成运行依赖
pip-compile pyproject.toml --output-file requirements.txt
# 若需要包含构建依赖（比如setuptools），加上--extra=build
pip-compile pyproject.toml --extra=build --output-file requirements.txt

3. 下载所有依赖到指定目录：

pip download --dest ./offline_packages -r requirements.txt
# 若需要下载项目本身的包，补充运行
pip download --dest ./offline_packages .

五、解决你之前尝试的问题 #

1. pip install --no-cache-dir -e .还是下载到缓存：
   --no-cache-dir的作用是禁止pip读取已有的缓存包（即不使用~/.cache/pip里的旧包），但pip下载新包时仍会临时存储到缓存目录再安装。如果要保存包用于离线，应该用pip download而非pip install——pip download是专门用来把包持久化保存到指定目录的工具。

2. pip download -r pyproject.toml报错：
   -r参数仅支持requirements.txt格式的文件，不兼容pyproject.toml。你可以用pip-compile转成requirements.txt，或者直接用pip download .自动解析pyproject.toml。

六、手动构建项目包的命令 #

如果你想手动生成项目的whl包（比如离线安装时不需要携带项目代码），可以用build工具：

1. 安装build：

pip install build

2. 进入项目根目录运行：

python -m build

这个命令会读取pyproject.toml，在dist目录生成项目的.whl和.tar.gz包，你可以把这些包加入offline_packages用于离线安装。