main/browser字段必须指向编译后产物，如"./out/extension.js"或"./dist/extension.js"，路径为运行时相对路径而非源码路径；webview资源须经webview.aswebviewuri()转换，静态路径须用path.join()拼接并配合vscode.uri.file()构造。
package.json 的 main/browser 字段必须指向构建产物
VSCode 插件启动时只加载 main（桌面端）或 browser（Web 扩展）字段指定的 JS 文件，且该路径是相对于插件根目录的**运行时路径**，不是源码路径。硬写 "./src/extension.ts" 会导致 Cannot find module 错误。
- TS 项目：
main必须为"./out/extension.js"，并确保tsc构建后out/目录存在 - esbuild/vite 项目：改用
"./dist/extension.js"，同时更新构建配置输出路径 -
browser字段不能复用main值——Web 环境不支持require()，所有依赖必须静态可分析 - 绝对禁止在路径中使用
../跳出插件根目录，VSCode 加载器会直接报Unable to resolve
静态资源路径必须用 vscode.Uri.file() 构造
直接拼字符串如 "./media/icon.svg" 在远程开发（SSH/WSL）、多根工作区或 Web 扩展中必然失效，因为文件系统上下文和运行时路径不一致。
- 正确做法：用
vscode.Uri.file(path.join(context.extensionPath, "media", "icon.svg")) -
context.extensionPath是插件安装后的实际磁盘路径，每次启动都可靠；__dirname在打包后可能指向临时目录，不可信 - 图标用于
package.json的icon字段时，只能写相对路径（如"media/icon.png"），且仅支持 PNG，不支持 SVG
WebView 中的资源引用必须过 webview.asWebviewUri()
即使路径本身正确，HTML 中直接写 <link href="./style.css"> 或 <script src="./script.js"></script> 也会被 CSP 拦截，表现为白屏或控制台报 Refused to load resource。
- 所有 CSS/JS/image 资源都必须先调用
webview.asWebviewUri(uri)转换 - 转换前的
uri仍需用vscode.Uri.file()构造，不能传入字符串路径 - 不要试图用
vscode.Uri.parse("https://...")绕过——CSP 只信任经asWebviewUri签名的本地资源
跨平台路径分隔符必须用 path.join()，不能硬写 / 或
Windows 下写 "./mediaicon.png" 或 "C:/my/ext/media/icon.png" 可能“碰巧”工作，但 Linux/macOS 下必然失败；Node.js 的 fs 模块在不同平台对非法分隔符的容忍度也不一致。
- 所有路径拼接必须用
path.join(a, b, c)，由 Node.js 自动选择分隔符 - 避免手动替换斜杠：
str.replace(/\/g, "/")不解决根本问题，且在 WSL 等混合环境中可能引入新错误 - 若需生成 URL 路径（如 WebView 中的
href），也应先用path.join()构造文件系统路径，再转Uri，最后过asWebviewUri()
out/ 或 dist/ 目录结构，并在 SSH/WSL 环境中实测资源加载。
