102、【OS】【Nuttx】【周边】文档构建渲染：安装 Esbonio 服务器

【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除

背景

接之前 blog
【OS】【Nuttx】【周边】文档构建渲染：reStructuredText 格式
之前 blog 分析了 reStructuredText 文件格式，和 VSCode 相关扩展的安装，其中介绍了 Esbonio 扩展，在 VSCode 中，安装了 Esbonio 扩展，还不能实时渲染 rst 文件，因为 Esbonio 扩展只是前端，需要安装 Esbonio 服务器才能进行渲染，下面分析 Esbonio 服务器

安装 Esbonio 服务器

首先，Esbonio 需要在 Python 环境中运行，终端输入

python3 --version

检查 python 版本 ok

终端输入

python3 -m pip --version

检查 python 包管理模块 pip 已安装 ok

终端输入

python3 -m pip install esbonio

尝试安装 esbnio 语言服务器，可以看到出现如下报错

adminpc@adminpc-M600:~/nuttx_pdt$ python3 -m pip install esbonio
error: externally-managed-environment× This environment is externally managed
╰─> To install Python packages system-wide, try apt installpython3-xyz, where xyz is the package you are trying toinstall.If you wish to install a non-Debian-packaged Python package,create a virtual environment using python3 -m venv path/to/venv.Then use path/to/venv/bin/python and path/to/venv/bin/pip. Makesure you have python3-full installed.If you wish to install a non-Debian packaged Python application,it may be easiest to use pipx install xyz, which will manage avirtual environment for you. Make sure you have pipx installed.See /usr/share/doc/python3.12/README.venv for more information.note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

下面来分析这个报错

• 首先，这是 Python 3.12+ 在 Ubuntu/Debian 中引入的一项安全机制，防止 pip 随意修改系统级的 Python 环境，避免破坏系统依赖
• Debian 是使用 Linux 内核和 GNU 工具集的开源计算机操作系统，而 Ubuntu 是基于 Debian 构建，在 Debian 的基础上增加了如图形化界面，系统配置工具等用户友好特性的桌面操作系统
• Debian 系管理的 Python 环境（比如 Ubuntu，Debian 等）中，系统自带的 Python 会运行一些关键工具（比如 apt、systemd 启动脚本等），如果直接用 python3 -m pip install 安装第三方包，可能会覆盖系统依赖，导致系统不稳定或崩溃，所以从 Python 3.12 开始，Debian 团队启用了 PEP 668，禁止直接用 pip 安装包到系统 Python 环境

当然，错误提示也推荐了三种方法

• 使用系统包管理器，比如 apt install python3-esbonio，这取决于 Ubuntu/Debian 是否提供了 esbonio 的 .deb 包，但目前看 esbonio 没有被收录进官方仓库，所以这条路走不通
• 使用虚拟环境，最标准，最推荐的做法（这里先不用，后面有机会再尝试）
• 使用 pipx 安装，pipx 是专门用来安装 Python 命令行应用的工具，会自动为每个应用创建独立的虚拟环境

这里 note 提示说可以加 --break-system-packages，虽然能强制安装，但很暴力，并且违背了系统设计原则，会破坏系统 Python 环境

下面为了不破坏系统 Python，下面再多加个选项 --user

python3 -m pip install --user esbonio --break-system-packages

虽然此时还有选项 --break-system-packages，但不会真的破坏系统，只是说服 pip 忽略 EXTERNALLY-MANAGED 错误

此时包安装在用户本地目录 ~/.local/lib/python3.12/site-packages，不影响系统其他用户，也不修改 /usr 目录，只是绕过了警告锁

查看本地目录 ~/.local/lib/python3.12/site-packages

可以看到 esbonio 已安装完毕

ok，今天先到这里，下篇 blog 继续