必须将vscode重装到纯英文路径，因中文路径会导致git、调试器、python插件等底层依赖因utf-8与gbk编码冲突而启动失败，且无法通过配置修复。
中文路径与文件名在插件测试中触发的 fs 操作失败
插件在本地开发时一切正常，但一到用户真实环境就报 ENOENT 或 EPERM —— 八成是测试没覆盖中文路径场景。Node.js 的 fs API 在 Windows 和部分 Linux 发行版上对 UTF-8 路径处理不一致，尤其当插件调用 fs.readdir、fs.readFile 或通过 vscode.workspace.fs 读取用户打开的文件夹时，路径含中文极易出错。
实操建议：
- 测试脚本里必须显式构造含中文的临时路径：
path.join(os.tmpdir(), '测试文件夹', '源码.ts')，不能只用英文 mock - 避免直接拼接字符串路径，统一用
vscode.Uri.file()构造 URI，再交由vscode.workspace.fs处理——它内部做了平台适配 - CI 环境（如 GitHub Actions）默认 locale 是
C.UTF-8，需手动设置：env: LANG: zh_CN.UTF-8，否则child_process.exec调用外部命令时会乱码
插件 UI 中文文案被截断或换行异常
不是字体问题，而是 VSCode 渲染器对 CSS text-overflow 和 white-space 的支持有差异。中文字符无空格分隔，word-break: break-all 在某些 Electron 版本下会导致按钮文字错位，而 overflow: hidden 又容易把“配置项”截成“配置…”。
实操建议：
- 所有固定宽容器（如侧边栏树节点、状态栏文字）必须设
min-width，且值不低于 8ch（中文字符平均宽度） - 禁用
word-break: break-word，改用overflow-wrap: anywhere—— 它对中文分词更友好 - 用
vscode.window.createWebviewPanel嵌入 HTML 时，务必在<meta>中声明charset="utf-8"，否则 Webview 内部 DOM 解析中文会失真
activationEvents 中文命令 ID 导致插件无法激活
package.json 里写 "onCommand":"扩展.保存为UTF8" 看似合理，实际会静默失败。VSCode 的命令注册系统要求 command ID 必须符合 [a-z0-9\-\.]+ 正则，中文、全角标点、空格一律被忽略，最终注册成空字符串。
实操建议：
- command ID 只能用英文小写+短横线，例如
extension.saveAsUtf8，中文仅用于contributes.commands.title字段显示 - 在
activate函数里注册命令时，ID 必须和package.json严格一致，大小写敏感 ——extension.SaveAsUtf8和extension.saveAsUtf8是两个不同命令 - 测试激活逻辑时，别只看命令面板能否搜到，要用
vscode.commands.executeCommand('extension.saveAsUtf8')主动调用验证
语言包 i18n 未生效或 fallback 错乱
插件发布后用户反馈“还是英文”，查日志发现 vscode.env.language 返回 zh-Hans，但你的 nls.localize 却 fallback 到了 en。根本原因是 VSCode 的语言包加载机制依赖 package.nls.json 文件名中的 locale 标签，且不接受 zh-CN 这类变体写法。
实操建议：
- 语言包文件必须命名为
package.nls.zh-cn.json（小写、短横线），不能是zh_CN或zhHans - 在
package.json的contributes.configuration中定义设置项时，title和description字段必须引用%key%，而非直写中文字符串 - 调试时用
vscode.l10n.t('hello')替代vscode.nls.localize—— 前者是新 API，自动处理 locale fallback 链，后者需手动维护availableLanguages
