{"code":1,"msg":"成功","time":"1793358145","data":{"title":"RT-Thread Env Tool v2.0.3：自定义位置安装、终端自动激活与 WebUI 使用全记录","content":"最近把 RT-Thread 的 Env 工具链升级到了 v2.0.3，整理了一份完整的使用记录分享给大家：包括**自定义位置安装**（官方脚本只支持装到 `~\/.env`，装不进项目目录）、**Windows Terminal 一键自动激活**、**WebUI 使用**，以及实测过程中踩过的一些坑。希望对用 Env 2.0 的朋友有帮助，也欢迎在帖子里交流。\r\n\r\n> 文中出现的 `E:\\AZE-BlackCore-Agent\\WorkBuddy_EmbeddedSwEngineer_Space\\tools\\env` 是**作者本机示例路径**，请根据你自己的实际安装路径修改后再执行命令。\r\n\r\n## 一、Env 2.0 是什么：新一代构建工具链\r\n\r\nRT-Thread Env 是官方提供的工程辅助工具，承担**项目配置（menuconfig）、软件包管理（pkgs）、SDK\/工具链管理（sdk）、固件构建（scons）**四大职责。从 v2.0 起做了架构性重构：\r\n\r\n- **命令统一入口改为 `rt-env`**：`menuconfig`、`pkgs`、`scons` 不再是散装的 env 子命令，而是 `rt-env` 的子命令体系，并新增 `sdk`、`plugin`、`webui`、`system`；\r\n- **依赖全部跑在 Python 虚拟环境（venv）中**：`rt-env`、`scons`、`pkgs`、`menuconfig`、`webui` 都是 venv 里生成的入口，依赖与系统 Python 隔离，避免污染；\r\n- **引入插件体系（plugin）与 Web 界面（webui）**：可以在浏览器里完成工具链\/SDK\/软件包管理，这是 v1.x 时代没有的能力；\r\n- **每个终端必须先\"激活\"**：`rt-env` 不在系统 PATH 里，需要 dot-source 启动脚本后才有命令可用。\r\n\r\n本机验证的版本组合：\r\n\r\n| 组件 | 版本 |\r\n| --- | --- |\r\n| rt-env | v2.0.3 |\r\n| SCons | 4.11.1 |\r\n| kconfiglib | 14.1.0 |\r\n| pyyaml | 6.0.3 |\r\n| windows-curses | 已装（menuconfig TUI 依赖） |\r\n\r\n> ⚠️ **兼容性红线**：Env v2.0 完整支持 **RT-Thread > 5.1.0 或 master 分支**；如果工程还在 5.1.0 及更早版本，请继续使用 v1.5.x（官方 `env-windows` 发行包），否则配置\/构建可能不兼容。\r\n\r\n## 二、环境准备\r\n\r\n安装前确认本机已有：\r\n\r\n```powershell\r\ngit --version      # 需要 Git，如 2.55.0\r\npython --version   # 需要 Python 3（推荐 3.10+，本机验证 3.13.16）\r\n```\r\n\r\n并遵守一条铁律：**安装路径不含中文、不含空格**（工具链内部大量脚本对路径敏感）。\r\n\r\n## 三、自定义位置安装 v2.0.3（核心步骤）\r\n\r\n### 3.1 为什么需要\"手动复刻\"\r\n\r\n官方脚本 `install_windows.ps1` \/ `touch_env.ps1` 把环境位置**写死为 `~\/.env`（用户主目录）**，不支持自定义安装目录。而团队项目通常希望把工具链放进**项目目录内的工具目录**（例如 `<项目>\/tools\/env`），随项目一起管理、便于多机复用。\r\n\r\n### 3.2 目录结构\r\n\r\n自定义安装的目标结构（以本机为例）：\r\n\r\n```\r\n<项目>\/tools\/env\/\r\n├── env.ps1              # 激活启动器（master 版本自带）\r\n├── .venv\/               # Python 虚拟环境（首次激活自动创建）\r\n├── local_pkgs\/          # 本地软件包缓存（可空）\r\n├── packages\/\r\n│   ├── Kconfig          # 软件包菜单入口（内容见下）\r\n│   ├── packages\/        # 软件包索引仓库（Gitee 镜像克隆）\r\n│   └── sdk\/             # SDK\/工具链仓库\r\n└── tools\/\r\n    └── scripts\/         # ENV 源码仓库（master = v2.0.3）\r\n```\r\n\r\n### 3.3 安装步骤（PowerShell）\r\n\r\n```powershell\r\n$envRoot = \"<项目>\\tools\\env\"\r\n\r\n# 1. 建目录结构\r\nNew-Item -ItemType Directory -Force -Path \"$envRoot\\local_pkgs\", \"$envRoot\\packages\", \"$envRoot\\tools\" | Out-Null\r\n\r\n# 2. 克隆软件包索引（国内网络用 Gitee 镜像，origin 保留镜像便于更新）\r\ngit clone https:\/\/gitee.com\/RT-Thread\/packages.git \"$envRoot\\packages\\packages\"\r\n\r\n# 3. 写入 packages\/Kconfig（软件包菜单入口）\r\nSet-Content -LiteralPath \"$envRoot\\packages\\Kconfig\" -Value 'source \"$PKGS_DIR\/packages\/Kconfig\"' -Encoding utf8\r\n\r\n# 4. 克隆 SDK\/工具链仓库\r\ngit clone https:\/\/gitee.com\/RT-Thread\/sdk.git \"$envRoot\\packages\\sdk\"\r\n\r\n# 5. 克隆 ENV 源码（v2.0.3 = master；可用官方仓库或自建镜像仓库）\r\ngit clone https:\/\/gitee.com\/<你的仓库>\/env.git \"$envRoot\\tools\\scripts\"\r\n# 或官方：git clone https:\/\/github.com\/RT-Thread\/env.git \"$envRoot\\tools\\scripts\"\r\n\r\n# 6. 复制激活启动器到 env 根\r\nCopy-Item \"$envRoot\\tools\\scripts\\env.ps1\" \"$envRoot\\env.ps1\"\r\n```\r\n\r\n### 3.4 版本身份确认\r\n\r\nEnv v2.0.3 **没有独立的 git tag**，`master` 分支即 v2.0.3。安装后确认：\r\n\r\n```powershell\r\nGet-Content \"$envRoot\\tools\\scripts\\env.json\"   # version = \"v2.0.3\"\r\n```\r\n\r\n如果 `env.ps1` 是旧版本（如 2.0.0 tag），它可能**不会自动设置 `ENV_ROOT`**，导致软件包索引指向默认的 `~\/.env`——需在 `env.ps1` 顶部手工补两行：\r\n\r\n```powershell\r\n$env:ENV_ROOT = $PSScriptRoot\r\n$env:PKGS_DIR  = Join-Path $PSScriptRoot \"packages\"\r\n```\r\n\r\n（master 版本已自带 `$PSScriptRoot` 定位，无需补丁。）\r\n\r\n## 四、激活与验证\r\n\r\n每个新终端执行一次激活：\r\n\r\n```powershell\r\n. \"E:\\AZE-BlackCore-Agent\\WorkBuddy_EmbeddedSwEngineer_Space\\tools\\env\\env.ps1\"   # 示例路径，请替换为你的实际安装路径\r\n```\r\n\r\n首次激活会自动完成：检测本机 IP 选择国内镜像（阿里云 PyPI）→ 创建 `.venv` → 安装 `rt-env` 及依赖（SCons、pyyaml、kconfiglib 等）。成功后输出欢迎页：\r\n\r\n```\r\n===================================================================\r\n    Welcome to RT-Thread Env Tool v2.0.3\r\n===================================================================\r\nEnvironment Information:\r\n  - ENV_ROOT : E:\\AZE-BlackCore-Agent\\WorkBuddy_EmbeddedSwEngineer_Space\\tools\\env\r\n  - PKGS_ROOT: E:\\AZE-BlackCore-Agent\\WorkBuddy_EmbeddedSwEngineer_Space\\tools\\env\\packages\r\n===================================================================\r\n```\r\n\r\n（以上为示例输出，`ENV_ROOT` \/ `PKGS_ROOT` 会显示你自己机器上的安装位置）\r\n\r\n验证命令：\r\n\r\n```powershell\r\nrt-env -v          # RT-Thread Env Tool v2.0.3\r\nrt-env --info      # 环境信息\r\nrt-env --help      # 子命令列表：system\/menuconfig\/pkg\/pkgs\/package\/sdk\/plugin\/webui\r\nscons --version    # SCons v4.11.1\r\n```\r\n\r\n## 五、Windows Terminal 启动项：新开终端自动激活\r\n\r\n每次都手动激活很烦，可以在 **Windows Terminal** 里配置一个专用启动项，打开即进入 ENV 环境。\r\n\r\n### 5.1 配置文件位置\r\n\r\n```text\r\n%LOCALAPPDATA%\\Packages\\Microsoft.WindowsTerminal_8wekyb3d8bbwe\\LocalState\\settings.json\r\n```\r\n\r\n> 修改前先备份：`Copy-Item settings.json settings.json.bak`\r\n\r\n### 5.2 启动项写法（正确示例）\r\n\r\n在 `profiles.list` 中新增（或修正）一个 profile：\r\n\r\n```json\r\n{\r\n    \"guid\": \"{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\",\r\n    \"name\": \"RT-Thread ENV-2.0.3\",\r\n    \"hidden\": false,\r\n    \"commandline\": \"powershell.exe -NoExit -ExecutionPolicy Bypass -Command \\\". 'E:\\\\AZE-BlackCore-Agent\\\\WorkBuddy_EmbeddedSwEngineer_Space\\\\tools\\\\env\\\\env.ps1'\\\"\"\r\n}\r\n```\r\n\r\n> 示例路径，请替换为你的实际安装路径（JSON 中反斜杠须写成 `\\\\`）。\r\n\r\n关键参数说明：\r\n\r\n| 参数 | 作用 |\r\n| --- | --- |\r\n| `-NoExit` | 激活后不退出终端，保持交互 |\r\n| `-ExecutionPolicy Bypass` | 绕过执行策略限制（Windows 默认 Restricted 禁止 .ps1） |\r\n| `-Command \". '...\\env.ps1'\"` | dot-source 激活脚本，命令结束后会话内生效 |\r\n\r\n### 5.3 常见错误写法（勿踩）\r\n\r\n```json\r\n\"commandline\": \"%SystemRoot%\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\\\\ . \\\"...env.ps1\\\"\"\r\n```\r\n\r\n这种把可执行文件路径和命令**用反斜杠硬拼**的写法不是合法命令行，Windows Terminal 启动该 profile 会直接失败（本机实测踩到）。可执行文件与参数之间必须是**空格**，且通过 `-Command` 传递。\r\n\r\n### 5.4 使用\r\n\r\nWindows Terminal → 标签页右侧 **▾ 下拉箭头** → 选择 **\"RT-Thread ENV-2.0.3\"**，新标签页即自动激活 ENV。若希望默认打开就是这个环境，把 `defaultProfile` 改为该 profile 的 guid 即可。\r\n\r\n## 六、常用命令速查\r\n\r\n进入 BSP 工程根目录后：\r\n\r\n| 命令 | 用途 |\r\n| --- | --- |\r\n| `menuconfig` | 交互式图形化配置（TUI），保存后生成 `rtconfig.h` |\r\n| `pkgs --update` | 按 `menuconfig` 选择同步\/拉取软件包 |\r\n| `scons -j8` | 多线程构建固件（`-c` 清理） |\r\n| `scons --target=mdk5` | 生成 Keil MDK 工程（同理 `--target=iar\/...`） |\r\n| `rt-env -v` \/ `--info` | 版本 \/ 环境信息 |\r\n| `rt-env sdk --install <sdk>` | 安装 SDK |\r\n| `rt-env plugin list` | 查看已安装插件 |\r\n| `rt-env webui` | 启动 Web 界面（见下） |\r\n\r\n## 七、WebUI：在浏览器里管理 Env\r\n\r\nv2.0.3 新增的 Web 界面可以在浏览器完成工具链、SDK、软件包与 BSP 构建管理。\r\n\r\n### 7.1 启动（推荐：前台模式）\r\n\r\n```powershell\r\nrt-env webui\r\n```\r\n\r\n启动后终端打印两个 URL，并自动打开浏览器：\r\n\r\n```\r\nEnv WebUI: http:\/\/127.0.0.1:64084\/\r\nLaunch URL: http:\/\/127.0.0.1:64084\/_launch\/DeT610f...（一次性令牌）\r\n```\r\n\r\n- 浏览器未自动打开时，手动访问 **Launch URL**（含一次性令牌，免密自动登录跳转）；\r\n- 停止：终端按 **Ctrl+C**；\r\n- 指定端口：`rt-env webui --port 8080`；\r\n- 局域网访问：`rt-env webui -g`（明文 HTTP，慎用）。\r\n\r\n### 7.2 已知限制：后台守护模式\r\n\r\n`rt-env webui start`（后台守护，支持 stop\/status）在**部分 Windows 环境不可用**，报 `WebUI service did not become available`。根因：一些工具链（如豆包工作环境）提供的 venv `python.exe` 是**启动器 stub**，会再拉起一层真实解释器，导致子进程无法在源码写死的 10 秒超时内完成就绪握手（服务器本身完全正常，前台模式实测通过）。遇到此类环境直接用**前台模式**即可。\r\n\r\n## 八、踩坑记录（都是实测换来的）\r\n\r\n1. **PowerShell 脚本编码（UTF-8 BOM）**：含中文注释的 `.ps1` 必须保存为 **UTF-8 with BOM**；无 BOM 时 PowerShell 5.1 按 ANSI\/GBK 解码，注释里的中文会\"吞掉\"换行，导致 `if` 结构错乱，报 *意外的标记\"}\"*。写 PowerShell 文件务必注意编码。\r\n2. **ENV_ROOT 未设置**：旧版本 `env.ps1`（如 2.0.0 tag）不自动设置 `ENV_ROOT`，软件包会跑到默认 `~\/.env`；升级脚本或手工补丁（见 3.4）。\r\n3. **venv Python 启动器 stub**：部分 Windows 环境（沙箱\/工作台）的 venv `python.exe` 是启动器，进程树会嵌套（stub → 真实解释器），影响依赖子进程握手的后台功能（如 `webui start`）；优先用前台\/进程内模式。\r\n4. **官方发行包版本陷阱**：官网 `env-windows-v2.0.0` 发行包**内部实为 v1.5.x 经典体系**（版本号与内部体系不一致），且自带 Python 3.11.9、Git、ConEmu、QEMU、arm-none-eabi-gcc 10.3.1 等一揽子工具；需要 v2.0 新特性时请以 git 源码安装为准。\r\n5. **兼容性红线**：v2.0 只完整支持 RT-Thread > 5.1.0 \/ master；老工程回退 v1.5.x。\r\n6. **路径规范**：安装路径无中文、无空格，否则 Kconfig\/构建脚本易出诡异问题。\r\n\r\n## 九、总结\r\n\r\n- Env v2.0.3 是 RT-Thread 新一代构建工具链，`rt-env` 统一命令 + venv 隔离 + WebUI 是其三大特征；\r\n- 官方脚本不支持自定义位置，**手动复刻目录结构 + Gitee 镜像克隆**即可装到项目内工具目录；\r\n- **Windows Terminal 启动项**一行 `-Command \". 'env.ps1'\"` 实现开箱即用；\r\n- WebUI 用**前台模式** `rt-env webui` 最稳；\r\n- 记住几条红线：**老工程（≤5.1.0）用 v1.5.x，新工程用 v2.0；路径无中文无空格；.ps1 用 UTF-8 BOM**。\r\n\r\n以上就是全部内容，命令均在本机（Windows PowerShell 5.1 \/ 7）实测通过。大家如果遇到 Env 2.0 安装或使用的问题，欢迎在楼下交流，我看到都会回复。","updatetime":"2026-10-27 11:01:16","author":"黑核阿泽"}}