mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 09:10:41 +08:00
feat: 拆分 environment-setup 为 Python/Node.js 运行时双核心 + 父级路由
新增双核心 skill（深度集成 DesireCore Hatch/Volta + HTTP API + Socket.IO）： - python-runtime v1.0.1：Python 运行时管理 · 四级降级：HTTP API → Hatch CLI 绝对路径 → 系统包管理器 → pyenv · references：hatch-desirecore / pyenv-fallback / virtualenv / troubleshooting · scripts/probe-python.sh：输出 JSON 快照供 Claude 解析决策 - nodejs-runtime v1.0.1：Node.js 运行时管理 · 四级降级：HTTP API → Volta CLI → 系统包管理器/NodeSource → nvm/fnm · references：volta-desirecore / nvm-fallback / package-managers / troubleshooting · scripts/probe-node.sh：输出 JSON 快照（含 volta_tools / package_json_volta 等） environment-setup → dev-environment-setup v2.0.1（重命名 + 重写为 router）： - 从 1380 行手册瘦身为 ~150 行索引 - 仅负责容器（Docker/Podman）/ WSL2 / 办公依赖速查 / 系统工具 - references/desirecore-runtime.md 沉淀 Hatch/Volta 路径表 + HTTP API 速查 + Socket.IO 事件契约，作为两个核心 skill 的共享底座 - references/decision-tree.md 定义四级降级决策树 - scripts/probe.sh + probe.ps1 系统级 JSON 探测 三个 SKILL.md 的 L0 改为场景驱动结构（何时使用 / 何时不要用 / 怎么做）， 让 AI 凭名字与 L0 即可判断匹配场景。 注册更新： - builtin-skills.json：新增 python-runtime / nodejs-runtime / dev-environment-setup （原 environment-setup 移除），按字母序，共 21 个 skill - manifest.json：totalSkills 19→21，lastUpdated 2026-05-02 下游同步： - docx / pdf / xlsx / pptx 中的环境引用从 environment-setup 拆分为 python-runtime / nodejs-runtime / dev-environment-setup 三向指引 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
140
skills/nodejs-runtime/references/nvm-fallback.md
Normal file
140
skills/nodejs-runtime/references/nvm-fallback.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# nvm / fnm（L4 社区方案）
|
||||
|
||||
仅在以下情况启用：
|
||||
1. 用户明确要求 nvm / fnm
|
||||
2. 项目根目录已有 `.nvmrc` 文件且不存在 `package.json#volta`
|
||||
3. L1 (HTTP API) / L2 (Volta CLI) / L3 (系统包管理器) 全部失败
|
||||
|
||||
如条件不满足，**不要**主动建议 nvm——优先 DesireCore Volta。
|
||||
|
||||
## nvm（POSIX shell）
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
|
||||
|
||||
source ~/.zshrc # 或 ~/.bashrc
|
||||
|
||||
# 验证
|
||||
command -v nvm # 应返回 "nvm"（函数）
|
||||
```
|
||||
|
||||
`install.sh` 会自动追加加载片段到 `~/.zshrc` / `~/.bashrc`：
|
||||
```bash
|
||||
export NVM_DIR="$HOME/.nvm"
|
||||
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
|
||||
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
|
||||
```
|
||||
|
||||
### 使用
|
||||
|
||||
```bash
|
||||
# 列出可装 LTS
|
||||
nvm ls-remote --lts
|
||||
|
||||
# 安装
|
||||
nvm install 22 # 最新 22.x
|
||||
nvm install --lts # 最新 LTS
|
||||
nvm install 20.10.0 # 精确版本
|
||||
|
||||
# 切换
|
||||
nvm use 22
|
||||
nvm use --lts
|
||||
|
||||
# 默认
|
||||
nvm alias default 22
|
||||
|
||||
# 项目级（.nvmrc）
|
||||
echo "22" > .nvmrc
|
||||
nvm use # 读取 .nvmrc
|
||||
|
||||
# 已装
|
||||
nvm ls
|
||||
|
||||
# 卸载
|
||||
nvm uninstall 18
|
||||
```
|
||||
|
||||
### Windows（nvm-windows，独立项目）
|
||||
|
||||
```
|
||||
https://github.com/coreybutler/nvm-windows/releases
|
||||
```
|
||||
|
||||
下载安装包安装，重启终端。命令略有差异（无 `.nvmrc` 支持，需用 `nvm-windows-bridge` 之类的扩展）。
|
||||
|
||||
## fnm（Rust 实现，比 nvm 快）
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install fnm
|
||||
|
||||
# Linux
|
||||
curl -fsSL https://fnm.vercel.app/install | bash
|
||||
|
||||
# Windows
|
||||
winget install Schniz.fnm
|
||||
```
|
||||
|
||||
### 配置自动切换
|
||||
|
||||
```bash
|
||||
# zsh
|
||||
echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc
|
||||
|
||||
# bash
|
||||
echo 'eval "$(fnm env --use-on-cd --shell bash)"' >> ~/.bashrc
|
||||
|
||||
# fish
|
||||
fnm env --use-on-cd --shell fish | source
|
||||
```
|
||||
|
||||
`--use-on-cd` 让 `cd` 进入有 `.nvmrc` 的目录时自动切换。
|
||||
|
||||
### 使用
|
||||
|
||||
```bash
|
||||
fnm install 22
|
||||
fnm install --lts
|
||||
fnm use 22
|
||||
fnm default 22
|
||||
fnm ls
|
||||
fnm uninstall 18
|
||||
```
|
||||
|
||||
## .nvmrc / .node-version 约定
|
||||
|
||||
| 文件 | 工具支持 |
|
||||
|------|----------|
|
||||
| `.nvmrc` | nvm、fnm（默认） |
|
||||
| `.node-version` | fnm（默认）、nodenv |
|
||||
| `package.json#engines.node` | npm 安装时校验，不切换 |
|
||||
| `package.json#volta` | Volta（自动切换） |
|
||||
|
||||
存在 `package.json#volta` 时**优先尊重**它，不要让用户改用 nvm。
|
||||
|
||||
## 镜像加速
|
||||
|
||||
```bash
|
||||
# nvm
|
||||
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node/
|
||||
|
||||
# fnm
|
||||
fnm install --node-dist-mirror https://npmmirror.com/mirrors/node/ 22
|
||||
# 或全局
|
||||
export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node/
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
| 现象 | 排查 |
|
||||
|------|------|
|
||||
| `nvm: command not found` | shell 未 source nvm.sh，重启终端或 `source ~/.zshrc` |
|
||||
| `nvm` 在脚本里失效 | nvm 是 shell function 不是命令；脚本里需先 `source ~/.nvm/nvm.sh` |
|
||||
| `node: command not found`（nvm 已装） | 切换了 shell 但 nvm 没在新 shell 加载，添加加载片段 |
|
||||
| nvm 编译 Node 时网络超时 | 设镜像 `NVM_NODEJS_ORG_MIRROR` |
|
||||
| Windows nvm 切换无效 | 以管理员重新运行 nvm 安装包 |
|
||||
160
skills/nodejs-runtime/references/package-managers.md
Normal file
160
skills/nodejs-runtime/references/package-managers.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 包管理器策略（npm / pnpm / yarn）
|
||||
|
||||
## 选型建议
|
||||
|
||||
| 场景 | 推荐 |
|
||||
|------|------|
|
||||
| 默认（Node.js 自带） | npm |
|
||||
| 磁盘高效 / 严格依赖 / monorepo | **pnpm**（推荐） |
|
||||
| 项目已用 yarn | yarn classic / berry |
|
||||
| DesireCore 应用内 | Volta 管理任何之上 |
|
||||
|
||||
## 通过 DesireCore Volta 安装
|
||||
|
||||
```bash
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
export VOLTA_FEATURE_PNPM=1
|
||||
|
||||
"$VOLTA" install pnpm@latest
|
||||
"$VOLTA" install yarn@latest
|
||||
"$VOLTA" install npm@10
|
||||
```
|
||||
|
||||
或 HTTP API：
|
||||
|
||||
```bash
|
||||
BASE="https://127.0.0.1:$(cat ~/.desirecore/agent-service.port)/api/runtime"
|
||||
curl -sk -X POST "${BASE}/pkg/pnpm/install" -H "Content-Type: application/json" -d '{"version":"latest"}'
|
||||
```
|
||||
|
||||
## 项目级固定版本
|
||||
|
||||
### package.json#volta（首选）
|
||||
|
||||
```json
|
||||
{
|
||||
"volta": {
|
||||
"node": "22.11.0",
|
||||
"pnpm": "9.5.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在装了 Volta 的环境中 `cd` 进项目即自动切换。
|
||||
|
||||
### packageManager 字段（Corepack 标准）
|
||||
|
||||
```json
|
||||
{
|
||||
"packageManager": "pnpm@9.5.0"
|
||||
}
|
||||
```
|
||||
|
||||
由 Corepack（Node 16.10+ 自带）解析，被 npm/pnpm/yarn 自身识别。可与 Volta 共存。
|
||||
|
||||
## npm 全局安装
|
||||
|
||||
### 不要用 sudo
|
||||
|
||||
错误：
|
||||
```bash
|
||||
sudo npm install -g pkg # ❌ 文件 owner 变成 root，后续维护麻烦
|
||||
```
|
||||
|
||||
正确：改 npm 全局目录到用户目录。
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
|
||||
npm install -g pptxgenjs docx
|
||||
```
|
||||
|
||||
或用 Volta（自动隔离，无权限问题）：
|
||||
```bash
|
||||
volta install pptxgenjs # ❌ Volta 不直接装库；只能装 CLI 工具
|
||||
# 库依赖应通过项目 package.json 管理
|
||||
```
|
||||
|
||||
## pnpm 配置
|
||||
|
||||
```bash
|
||||
# 全局存储位置（pnpm 单存储多链接的核心）
|
||||
pnpm config get store-dir
|
||||
# 默认 ~/.local/share/pnpm/store/v3
|
||||
|
||||
# 改 registry
|
||||
pnpm config set registry https://registry.npmmirror.com/
|
||||
|
||||
# 全局安装路径（独立于 npm）
|
||||
pnpm config get global-bin-dir
|
||||
```
|
||||
|
||||
## yarn 配置
|
||||
|
||||
```bash
|
||||
# yarn classic
|
||||
yarn config set registry https://registry.npmmirror.com/
|
||||
|
||||
# yarn berry
|
||||
yarn config set npmRegistryServer https://registry.npmmirror.com/
|
||||
```
|
||||
|
||||
## 镜像 / 代理
|
||||
|
||||
### 中国大陆加速
|
||||
|
||||
```bash
|
||||
npm config set registry https://registry.npmmirror.com/
|
||||
pnpm config set registry https://registry.npmmirror.com/
|
||||
yarn config set registry https://registry.npmmirror.com/
|
||||
```
|
||||
|
||||
恢复官方：
|
||||
```bash
|
||||
npm config set registry https://registry.npmjs.org/
|
||||
```
|
||||
|
||||
### 公司代理
|
||||
|
||||
```bash
|
||||
npm config set proxy http://proxy:port
|
||||
npm config set https-proxy http://proxy:port
|
||||
|
||||
# 取消
|
||||
npm config delete proxy
|
||||
npm config delete https-proxy
|
||||
```
|
||||
|
||||
### 私有 registry（Verdaccio / Nexus）
|
||||
|
||||
```bash
|
||||
# 项目级（.npmrc）
|
||||
@scope:registry=https://npm.company.com/
|
||||
//npm.company.com/:_authToken=${NPM_TOKEN}
|
||||
```
|
||||
|
||||
## 卸载与清理
|
||||
|
||||
```bash
|
||||
# 全局列表
|
||||
npm ls -g --depth=0
|
||||
pnpm list -g --depth=0
|
||||
yarn global list
|
||||
|
||||
# 卸载
|
||||
npm uninstall -g pkg
|
||||
pnpm uninstall -g pkg
|
||||
yarn global remove pkg
|
||||
|
||||
# 清缓存
|
||||
npm cache clean --force
|
||||
pnpm store prune
|
||||
yarn cache clean
|
||||
```
|
||||
|
||||
## 环境快照
|
||||
|
||||
probe-node.sh 输出 `volta_tools.{node,pnpm,yarn,npm}` 列出所有 Volta 管理的版本，`registry` / `proxy` 来自 npm 配置。Skill 解析 JSON 即可判断是否需要切换镜像。
|
||||
173
skills/nodejs-runtime/references/troubleshooting.md
Normal file
173
skills/nodejs-runtime/references/troubleshooting.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# Node.js 故障排查
|
||||
|
||||
## "node: command not found" / "npm: command not found"
|
||||
|
||||
```bash
|
||||
# 1. 找一下二进制
|
||||
which node 2>/dev/null
|
||||
ls /usr/bin/node /usr/local/bin/node /opt/homebrew/bin/node 2>/dev/null
|
||||
|
||||
# 2. nvm 已装但未加载？
|
||||
[ -s "$HOME/.nvm/nvm.sh" ] && echo "nvm installed but not loaded"
|
||||
export NVM_DIR="$HOME/.nvm"
|
||||
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
|
||||
node --version
|
||||
|
||||
# 3. Volta 已装但未在 PATH？
|
||||
ls ~/.desirecore/runtime/volta/volta 2>/dev/null && \
|
||||
echo "运行 ~/.desirecore/runtime/volta/volta 直接调用，无需 PATH"
|
||||
```
|
||||
|
||||
**根治**：按主 SKILL.md 决策树重新执行 L1–L3 安装路径。
|
||||
|
||||
## npm EACCES（全局安装权限错误）
|
||||
|
||||
**症状**：`npm install -g <pkg>` 报 `EACCES: permission denied, mkdir '/usr/local/lib/node_modules'`。
|
||||
|
||||
**原因**：npm 默认全局目录是系统目录，无写权限。
|
||||
|
||||
**修复（推荐：改 npm prefix 到用户目录）**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc # 或 ~/.bashrc
|
||||
source ~/.zshrc
|
||||
|
||||
# 现在可以正常全局安装
|
||||
npm install -g pkg
|
||||
```
|
||||
|
||||
**禁忌**：`sudo npm install -g` ——会把文件 owner 改成 root，后续 npm 升级/卸载报错。
|
||||
|
||||
## node-gyp 编译失败
|
||||
|
||||
**症状**：安装包含原生扩展的依赖（sqlite3 / sharp / canvas）时报 `node-gyp rebuild failed`。
|
||||
|
||||
| 平台 | 修复 |
|
||||
|------|------|
|
||||
| macOS | `xcode-select --install` |
|
||||
| Ubuntu/Debian | `sudo apt install build-essential python3` |
|
||||
| Fedora/RHEL | `sudo dnf groupinstall "Development Tools" && sudo dnf install python3` |
|
||||
| Windows | `npm install --global windows-build-tools`（管理员）或装 Visual Studio Build Tools |
|
||||
|
||||
某些包提供预编译版本：检查 `package.json` 是否有 `prebuild-install` 钩子，没有再编译。
|
||||
|
||||
## SSL / TLS 错误
|
||||
|
||||
```bash
|
||||
# 临时不验证（仅调试）
|
||||
npm config set strict-ssl false
|
||||
|
||||
# 永久（不推荐）
|
||||
npm config set ca null
|
||||
|
||||
# 公司证书 / Zscaler
|
||||
npm config set cafile /path/to/company-ca.pem
|
||||
```
|
||||
|
||||
## 代理环境
|
||||
|
||||
```bash
|
||||
# 设置
|
||||
npm config set proxy http://proxy:port
|
||||
npm config set https-proxy http://proxy:port
|
||||
|
||||
# 检查
|
||||
npm config get proxy
|
||||
npm config get https-proxy
|
||||
|
||||
# 取消
|
||||
npm config delete proxy
|
||||
npm config delete https-proxy
|
||||
```
|
||||
|
||||
注意：HTTP_PROXY / HTTPS_PROXY 环境变量也会被 npm 识别。
|
||||
|
||||
## "Cannot find module" 错误
|
||||
|
||||
```bash
|
||||
# 1. 是否在正确目录
|
||||
pwd
|
||||
ls package.json
|
||||
|
||||
# 2. node_modules 是否安装
|
||||
ls node_modules/<missing-module> 2>/dev/null
|
||||
|
||||
# 3. 是否在虚拟切换中（nvm/Volta 没切对）
|
||||
node -e "console.log(process.execPath)"
|
||||
|
||||
# 4. 重装
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## 版本冲突
|
||||
|
||||
`package.json#engines` 限制 Node 版本：
|
||||
|
||||
```json
|
||||
{
|
||||
"engines": { "node": ">=20" }
|
||||
}
|
||||
```
|
||||
|
||||
Volta 会强制使用 `volta` 字段；nvm/fnm 用 `.nvmrc`。检查冲突：
|
||||
|
||||
```bash
|
||||
node --version
|
||||
cat package.json | grep -A2 '"volta"\|"engines"'
|
||||
cat .nvmrc 2>/dev/null
|
||||
```
|
||||
|
||||
## Windows PowerShell 执行策略
|
||||
|
||||
```powershell
|
||||
Get-ExecutionPolicy
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
```
|
||||
|
||||
之后才能运行 npm / pnpm / yarn 脚本。
|
||||
|
||||
## 镜像与 CDN 慢
|
||||
|
||||
```bash
|
||||
# 切换到淘宝镜像
|
||||
npm config set registry https://registry.npmmirror.com/
|
||||
pnpm config set registry https://registry.npmmirror.com/
|
||||
|
||||
# 部分二进制（sharp / puppeteer）有独立 CDN
|
||||
export SHARP_DIST_BASE_URL=https://npmmirror.com/mirrors/sharp/
|
||||
export PUPPETEER_DOWNLOAD_HOST=https://npmmirror.com/mirrors/
|
||||
```
|
||||
|
||||
## EnvironmentSnapshot 信号速查
|
||||
|
||||
probe-node.sh 输出后，按字段快速判断：
|
||||
|
||||
| 字段 | 期望 | 失败原因 |
|
||||
|------|------|----------|
|
||||
| `system_node.version` | 非空且 ≥ 18 | 未装或版本太低 |
|
||||
| `system_npm.version` | 非空 | 应随 Node 自带 |
|
||||
| `volta_path` | 非空 | DesireCore Volta 未释放，调 `POST /api/runtime/volta/install` |
|
||||
| `volta_tools.node` | 非空数组 | 还未装任何 Volta 管理的 Node 版本 |
|
||||
| `package_json_volta` | 项目用 Volta | 优先 Volta，不要切到 nvm |
|
||||
| `registry` | `*.npmmirror.com` | 已加速；空字符串可能是 npm 未装 |
|
||||
| `proxy` | 非空 | 公司代理已设；如有问题先查代理 |
|
||||
|
||||
## 重置整个 Node.js 环境（最后手段）
|
||||
|
||||
```bash
|
||||
# 1. 删除全局缓存
|
||||
npm cache clean --force
|
||||
pnpm store prune
|
||||
yarn cache clean
|
||||
|
||||
# 2. 删除项目锁文件 + node_modules
|
||||
rm -rf node_modules package-lock.json pnpm-lock.yaml yarn.lock
|
||||
|
||||
# 3. 重新探测
|
||||
bash skills/nodejs-runtime/scripts/probe-node.sh
|
||||
|
||||
# 4. 按主 SKILL.md 决策树重新安装并 install
|
||||
```
|
||||
165
skills/nodejs-runtime/references/volta-desirecore.md
Normal file
165
skills/nodejs-runtime/references/volta-desirecore.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# DesireCore 内置 Volta（L1 / L2 主路径）
|
||||
|
||||
DesireCore 内置 [Volta](https://volta.sh/) v2.0.2（Rust 实现的 Node.js 工具链管理器）。Volta 二进制随应用打包于 `static/volta/`，运行时位于 `~/.desirecore/runtime/volta/`，**用户无需单独安装**。
|
||||
|
||||
> 与系统 Node.js 完全隔离：Volta 安装的工具位于 `~/.desirecore/runtime/volta/tools/image/`，不修改系统 PATH。
|
||||
|
||||
## L1：通过 HTTP API 操作（推荐，DesireCore 应用内）
|
||||
|
||||
### 探测 API 可用性
|
||||
|
||||
```bash
|
||||
PORT_FILE="$HOME/.desirecore/agent-service.port"
|
||||
[ -r "$PORT_FILE" ] || { echo "API 不可用，降级到 L2"; exit 1; }
|
||||
PORT=$(cat "$PORT_FILE")
|
||||
BASE="https://127.0.0.1:${PORT}/api/runtime"
|
||||
|
||||
curl -sk --max-time 0.5 "${BASE}/environment" >/dev/null \
|
||||
|| { echo "API 超时，降级到 L2"; exit 1; }
|
||||
```
|
||||
|
||||
### Volta 自身
|
||||
|
||||
```bash
|
||||
curl -sk "${BASE}/volta/status"
|
||||
curl -sk -X POST "${BASE}/volta/install" # 自动下载到 runtime/
|
||||
```
|
||||
|
||||
### Node.js 版本
|
||||
|
||||
```bash
|
||||
# 已装版本
|
||||
curl -sk "${BASE}/node/installed"
|
||||
|
||||
# 可装版本（远端 nodejs.org/dist 或 GitHub Releases）
|
||||
curl -sk "${BASE}/node/available"
|
||||
# ❗ 若返回 502，说明远端 / 镜像不可达，立即降级到 L2
|
||||
|
||||
# 安装（异步，立即返回 taskId）
|
||||
curl -sk -X POST "${BASE}/node/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"22"}'
|
||||
|
||||
# 移除
|
||||
curl -sk -X POST "${BASE}/node/remove" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"20.10.0"}'
|
||||
```
|
||||
|
||||
### 包管理器（pnpm / yarn / npm）
|
||||
|
||||
```bash
|
||||
TOOL="pnpm" # 或 yarn / npm
|
||||
|
||||
curl -sk "${BASE}/pkg/${TOOL}/installed"
|
||||
curl -sk "${BASE}/pkg/${TOOL}/available"
|
||||
|
||||
curl -sk -X POST "${BASE}/pkg/${TOOL}/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"latest"}'
|
||||
|
||||
curl -sk -X POST "${BASE}/pkg/${TOOL}/remove" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"9.0.0"}'
|
||||
```
|
||||
|
||||
### 实时输出 / 缓存刷新
|
||||
|
||||
异步任务：监听 Socket.IO 事件 `runtime:terminal` / `runtime:complete`，按 taskId 过滤。
|
||||
|
||||
```bash
|
||||
curl -sk -X POST "${BASE}/environment/refresh" # 安装结束后刷新
|
||||
```
|
||||
|
||||
## L2：直接调用 Volta CLI 绝对路径
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
```bash
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
export VOLTA_HOME=~/.desirecore/runtime/volta
|
||||
export VOLTA_FEATURE_PNPM=1
|
||||
# export VOLTA_NODE_MIRROR=https://npmmirror.com/mirrors/node # 中国大陆加速
|
||||
|
||||
# 安装
|
||||
"$VOLTA" install node@22 # 最新 22.x
|
||||
"$VOLTA" install node@20.11.0 # 精确版本
|
||||
"$VOLTA" install pnpm@latest
|
||||
"$VOLTA" install yarn@latest
|
||||
"$VOLTA" install npm@10
|
||||
|
||||
# 列表
|
||||
"$VOLTA" list all
|
||||
"$VOLTA" list node
|
||||
|
||||
# 项目级固定（写入 package.json#volta）
|
||||
"$VOLTA" pin node@22 pnpm@9
|
||||
```
|
||||
|
||||
`volta pin` 后 `package.json` 中会自动追加：
|
||||
```json
|
||||
"volta": {
|
||||
"node": "22.11.0",
|
||||
"pnpm": "9.5.0"
|
||||
}
|
||||
```
|
||||
|
||||
后续 `cd` 进项目目录时 Volta 自动激活对应版本。
|
||||
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
$Volta = "$env:USERPROFILE\.desirecore\runtime\volta\volta.exe"
|
||||
$env:VOLTA_HOME = "$env:USERPROFILE\.desirecore\runtime\volta"
|
||||
$env:VOLTA_FEATURE_PNPM = "1"
|
||||
|
||||
& $Volta install node@22
|
||||
& $Volta install pnpm@latest
|
||||
& $Volta list all
|
||||
```
|
||||
|
||||
### 移除
|
||||
|
||||
Volta 没有 `volta uninstall node`，直接删目录或用 HTTP API：
|
||||
|
||||
```bash
|
||||
rm -rf ~/.desirecore/runtime/volta/tools/image/node/<version>
|
||||
```
|
||||
|
||||
或：
|
||||
```bash
|
||||
curl -sk -X POST "${BASE}/node/remove" -H "Content-Type: application/json" -d '{"version":"22.11.0"}'
|
||||
```
|
||||
|
||||
## 可视化管理
|
||||
|
||||
DesireCore 应用 → 资源管理器 → 计算资源 → **运行环境** Tab，GUI 安装/删除 Node.js 与包管理器。
|
||||
|
||||
## 版本自动切换（核心优势）
|
||||
|
||||
只要 `package.json` 中有 `volta` 字段，Volta 会在 `cd` 进入目录时**自动激活**对应版本。无需手动 `volta use`，也无需 `.nvmrc`。
|
||||
|
||||
## Volta vs nvm
|
||||
|
||||
| 维度 | Volta（DesireCore 内置） | nvm（社区） |
|
||||
|------|--------------------------|-------------|
|
||||
| 安装方式 | 随 DesireCore 内置 | 用户手动 |
|
||||
| 版本切换 | **自动**（基于 package.json） | 手动 `nvm use` 或 `.nvmrc` |
|
||||
| 包管理器 | 支持（pnpm/yarn/npm 都可固定版本） | 不支持 |
|
||||
| Windows 原生 | ✅ | 需 nvm-windows（功能受限） |
|
||||
| 速度 | 极快（Rust 实现） | 较慢（shell 脚本） |
|
||||
| 系统 PATH | 不污染 | 修改 PATH |
|
||||
| GUI | DesireCore 运行环境 Tab | 无 |
|
||||
| 镜像加速 | `VOLTA_NODE_MIRROR` | 无内建支持 |
|
||||
|
||||
**结论**：DesireCore 应用内、有 Volta 时永远首选 Volta；外部脚本可考虑 nvm/fnm。
|
||||
|
||||
## 故障排查（Volta 专属）
|
||||
|
||||
| 现象 | 排查 |
|
||||
|------|------|
|
||||
| `volta: not found` | 二进制未释放，调 `POST /api/runtime/volta/install` |
|
||||
| `Volta error: Could not download node v22.x.x` | 网络或镜像问题，设 `VOLTA_NODE_MIRROR` |
|
||||
| `volta install pnpm` 报错 | 检查 `VOLTA_FEATURE_PNPM=1` 是否设置 |
|
||||
| Windows Defender 隔离 volta.exe | 信任 `~\.desirecore\runtime\volta\` 目录 |
|
||||
| `cd` 进项目后版本未切换 | 确认 `package.json` 中 `volta` 字段且 PATH 中 Volta shim 在最前 |
|
||||
Reference in New Issue
Block a user