mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 09:30:42 +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:
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
|
||||
```
|
||||
Reference in New Issue
Block a user