From 4202425ae00d89caafa86d8cf0cdcb57495fae46 Mon Sep 17 00:00:00 2001 From: whg517 Date: Sun, 13 Sep 2026 17:37:11 +0800 Subject: [PATCH] docs: isolate Python CLI tool installations --- docs/introduction/virtualenv.md | 6 +++++- docs/practices/web.md | 8 ++++++-- docs/quick_start.md | 11 ++++++----- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/introduction/virtualenv.md b/docs/introduction/virtualenv.md index a38d0a5..2b0c93b 100644 --- a/docs/introduction/virtualenv.md +++ b/docs/introduction/virtualenv.md @@ -275,8 +275,12 @@ pipenv install tox **安装：** +Poetry 自身应安装在独立虚拟环境中，不要安装到系统 Python 或 Poetry 将要管理的项目虚拟环境。 +按照 [Poetry 官方安装说明](https://python-poetry.org/docs/#installation)，推荐使用 [pipx](https://pipx.pypa.io/stable/) 安装；pipx 会为 Poetry 创建和维护隔离环境，同时让 `poetry` 命令可在各项目中使用。 + ```bash -pip install poetry +pipx install poetry +poetry --version ``` **使用：** diff --git a/docs/practices/web.md b/docs/practices/web.md index a9216f5..2dd1093 100644 --- a/docs/practices/web.md +++ b/docs/practices/web.md @@ -20,9 +20,13 @@ ### 1.3 虚拟环境工具 -推荐使用 [poetry](https://python-poetry.org/)。poetry 相比使用 `requirements.txt` 管理依赖列表，更加强大。它支持同时管理开发生产环境依赖，自动查找虚拟环境，生成依赖锁定文件等其他特性。 +推荐使用 [Poetry](https://python-poetry.org/)。Poetry 相比使用 `requirements.txt` 管理依赖列表，更加强大。它支持同时管理开发生产环境依赖，自动查找虚拟环境，生成依赖锁定文件等其他特性。 -在安装好 Python 环境后，应该在全局环境中安装 poetry 。 +Poetry 命令可以在各项目中使用，但它自身的依赖应与系统 Python 和项目环境隔离。建议按照 [Poetry 官方安装说明](https://python-poetry.org/docs/#installation)，使用 [pipx](https://pipx.pypa.io/stable/) 将 Poetry 安装到独立虚拟环境中： + +```bash +pipx install poetry +``` ### 1.4 Git 使用 diff --git a/docs/quick_start.md b/docs/quick_start.md index d7a83a4..09bd87a 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -20,21 +20,22 @@ 推荐使用 [Poetry](https://python-poetry.org/) ，既包含了虚拟环境管理工具也支持打包发布等功能。 -在安装好 Python 环境后，应该在全局环境中安装 [Poetry](https://python-poetry.org/) 。 +Poetry 作为命令行工具可以在各项目中使用，但不应安装到系统 Python 或它所管理的项目虚拟环境中。推荐使用 [pipx](https://pipx.pypa.io/stable/) 为 Poetry 创建独立虚拟环境，并让 `poetry` 命令可在各项目中使用。 +若尚未安装 pipx，请先按照其[官方安装说明](https://pipx.pypa.io/stable/how-to/install-pipx.html)完成安装。 ```bash -sudo python -m pip install -U pip -sudo pip install -U poetry +pipx install poetry +poetry --version ``` ### 1.4 初始化项目 -[cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/README.html) 是一个通过项目模板创建项目的命令行工具。 +[cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) 是一个通过项目模板创建项目的命令行工具。 安装 cookiecutter ```bash -sudo pip3 install -U cookiecutter +pipx install cookiecutter ``` 初始化项目