vscode 二开踩坑记录

开发环境准备

How to contribute

npm ci报错:gyp相关报错

注意检查python版本和node-gyp的版本安装情况,严格按照这个文档:

建议:
- python: >= v3.12x
- node-gyp: >= v10
python版本尽量不要污染全局,可以采用pyenv来管理和设置当前终端的python版本

如果还报错, 实测如下方案:

最简修复：删坏缓存、重新拉取（走国内镜像秒下）

bash 复制代码

# 1. 清掉损坏的缓存
rm -rf ~/.cache/node-gyp/22.17.0

# 2. 国内镜像（任选其一）
export npm_config_disturl=https://cdn.npmmirror.com/binaries/node
# 或者
# export npm_config_disturl=https://npmmirror.com/mirrors/node

# 3. 重装
cd vscode
rm -rf build/node_modules build/package-lock.json
npm cache clean --force
npm install

如果镜像也 404，就再手动灌一次（保证完整性）

bash 复制代码

# 1. 删除坏目录
rm -rf ~/.cache/node-gyp/22.17.0

# 2. 重新下载并解压
mkdir -p ~/.cache/node-gyp/22.17.0
cd ~/.cache/node-gyp/22.17.0
wget https://nodejs.org/dist/v22.17.0/node-v22.17.0-headers.tar.gz
tar --strip-components=1 -xf node-v22.17.0-headers.tar.gz

# 3. 告诉 node-gyp 别联网
export npm_config_nodedir=$HOME/.cache/node-gyp/22.17.0

# 4. 重装
cd vscode
rm -rf build/node_modules build/package-lock.json
npm install

一键脚本（Ubuntu / Node 20+）

bash 复制代码

#!/usr/bin/env bash
set -e
cd vscode

# 1. 清理坏缓存
rm -rf ~/.cache/node-gyp/22.17.0

# 2. 国内镜像拉取
export npm_config_disturl=https://cdn.npmmirror.com/binaries/node

# 3. 重装
rm -rf build/node_modules build/package-lock.json
npm cache clean --force
npm install
echo "✅ tree-sitter rebuilt ok"

保存为 fix-tree-sitter.sh，chmod +x fix-tree-sitter.sh && ./fix-tree-sitter.sh 即可。最简修复：删坏缓存、重新拉取（走国内镜像秒下）

bash 复制代码

# 1. 清掉损坏的缓存
rm -rf ~/.cache/node-gyp/22.17.0

# 2. 国内镜像（任选其一）
export npm_config_disturl=https://cdn.npmmirror.com/binaries/node
# 或者
# export npm_config_disturl=https://npmmirror.com/mirrors/node

# 3. 重装
cd vscode
rm -rf build/node_modules build/package-lock.json
npm cache clean --force
npm install

如果镜像也 404，就再手动灌一次（保证完整性）

bash 复制代码

# 1. 删除坏目录
rm -rf ~/.cache/node-gyp/22.17.0

# 2. 重新下载并解压
mkdir -p ~/.cache/node-gyp/22.17.0
cd ~/.cache/node-gyp/22.17.0
wget https://nodejs.org/dist/v22.17.0/node-v22.17.0-headers.tar.gz
tar --strip-components=1 -xf node-v22.17.0-headers.tar.gz

# 3. 告诉 node-gyp 别联网
export npm_config_nodedir=$HOME/.cache/node-gyp/22.17.0

# 4. 重装
cd vscode
rm -rf build/node_modules build/package-lock.json
npm install

一键脚本（Ubuntu / Node 20+）

bash 复制代码

#!/usr/bin/env bash
set -e
cd vscode

# 1. 清理坏缓存
rm -rf ~/.cache/node-gyp/22.17.0

# 2. 国内镜像拉取
export npm_config_disturl=https://cdn.npmmirror.com/binaries/node

# 3. 重装
rm -rf build/node_modules build/package-lock.json
npm cache clean --force
npm install
echo "✅ tree-sitter rebuilt ok"

保存为 fix-tree-sitter.sh，chmod +x fix-tree-sitter.sh && ./fix-tree-sitter.sh 即可。

npm run watch 报错

一定使用 npm ci来安装依赖,严格遵循package-lock文件锁定的版本: 这些报错都是「TypeScript 类型对不上」------不是语法错误，而是 xterm 升级后接口变了 + Node.js 类型定义里 err 从 undefined 变成 null | undefined 。
解决思路：要么 回退依赖版本 （最快），要么 改源码适配新定义 （长期）。下面给出两套现成命令，按需求二选一即可让 npm run watch 重新变绿。

方案 1：回退到官方 lock 版本（1 分钟搞定）

把 node_modules 和编译缓存清掉

rm -rf node_modules

rm -rf out

rm -rf .build-cache
用官方 lock 文件重新装

npm ci # 必须 ci，不能用 install，否则 lock 被刷新
再 watch

npm run watch

→ 官方 lock 里 xterm 与 @types/node 版本是匹配的，一般 0 错误。

方案 2：手动适配新类型（想保持最新依赖时用）

错误 1
fastScrollModifier 已在 xterm@5.3+ 被删除，直接删掉或加 as any 即可：

diff 复制代码

// src/vs/workbench/contrib/terminal/browser/xterm/xtermTerminal.ts L226
- fastScrollModifier: 'alt',
+ // fastScrollModifier removed in xterm 5.3

错误 2 & 3

Node 18+ 的 err 回调签名变成 Error | null | undefined，把类型收窄即可：

diff 复制代码

// src/vs/workbench/api/node/extHostConsoleForwarder.ts L60
- (err?: Error | undefined) => void
+ (err?: Error | null | undefined) => void

// src/bootstrap-fork.ts L134 同理

改完保存，watch 会自动增量编译，3 个错误消失。

一句话总结

想继续开发 就用方案 1 回退依赖 ；

想追新 xterm/Node 就 用方案 2 改三行代码 。

改完再 npm run watch，终端里应该出现
[watch-client] Finished compilation with 0 errors after xxxx ms