插件更新后webview或预览页报404，主因是插件自身路径引用错误或构建产物未同步：硬编码相对路径（如"./dist/bundle.js"）未经vscode.uri.file()基于context.extensionpath正确拼接，导致vscode-webview://协议加载失败，实际文件存在但路径不匹配。
插件更新后静态资源加载失败，90% 是插件自身路径引用或构建产物未同步导致，不是 VSCode 问题，也不该先去改 settings.json 或清缓存。
为什么插件更新后 webview 或预览页报 404？
很多插件（如 Markdown Preview、Codex、REST Client）会在 Webview 中加载本地 HTML/CSS/JS，这些资源通常打包在插件目录的 out/、dist/ 或 media/ 子目录里。更新插件时，VSCode 会替换整个扩展文件夹，但旧版残留的缓存 URL 可能还被 Webview 持有，或新版本未正确生成资源路径。
- 典型现象：
Failed to load resource: the server responded with a status of 404 (Not Found)，请求路径类似vscode-webview://.../main.js或http://localhost:3000/static/logo.png - 根本原因：插件代码里用硬编码路径（如
./static/logo.png）或相对路径拼接，而 VSCode 的 Webview 资源服务只认插件根目录下经vscode.Uri.file()转换后的绝对路径 - 更新后常见断点：
package.json里的main字段指向了不存在的 JS 文件；webview.html中的<script src="dist/bundle.js"></script>实际文件在out/bundle.js
如何快速验证是插件资源路径错还是 VSCode 加载机制问题？
直接检查插件安装目录下的实际文件结构，和它运行时尝试加载的路径是否一致——这是最可靠的判断方式。
- 先定位插件路径：
~/.vscode/extensions/（Linux/macOS）或C:\Users\{用户名}\.vscode\extensions\（Windows），找对应插件文件夹（如ms-vscode.vscode-typescript-next-4.5.20231201） - 打开该文件夹，确认
dist/、out/或media/目录是否存在，且目标文件（如main.js、logo.svg）真实存在 - 在插件源码（如果开源）中搜索
vscode.Uri.file或webview.asWebviewUri调用，看它传入的路径是否基于context.extensionPath拼接；错误写法示例：vscode.Uri.file('./dist/main.js')→ 正确应为：vscode.Uri.file(path.join(context.extensionPath, 'dist', 'main.js')) - 若插件不开源，可临时用 ZIP 工具打开
.vsix文件，检查内部路径与package.json中声明的入口是否匹配
遇到 ERR_CONNECTION_REFUSED 或空白 Webview 怎么办？
这不是网络问题，而是插件试图启动一个本地 HTTP 服务（比如 Python Flask、Node Express）来 serve 静态资源，但该服务没起来、端口被占，或插件没权限监听端口。
- 常见于 AI 类插件（如 Codex）、数据库客户端类插件（如 Database Client），它们会起一个本地 server 提供 UI 接口
- 检查输出面板（
View → Output），切换到对应插件名称的通道，看是否有类似Port 8080 is already in use或Permission denied: listen EACCES的日志 - 手动杀掉占用进程：
lsof -i :8080（macOS/Linux）或netstat -ano | findstr ":8080"（Windows），再kill -9 {PID}或taskkill /F /PID {PID} - 某些插件需要用户显式授权才能绑定本地端口（尤其 macOS 上），首次启动时可能静默失败；可尝试右键插件图标 → “重新加载扩展”触发重试
插件更新后资源路径突然变大小写敏感？
Windows 和 macOS 默认文件系统不区分大小写，Linux（ext4）严格区分。如果你在 Windows/macOS 开发插件，路径写成 Logo.png，但发布后用户在 Linux 上安装，而插件代码里引用的是 logo.png，就会 404。
- 排查方法：在 Linux 环境下进入插件目录，执行
ls -l media/，确认文件名大小写与代码中引用完全一致 - 构建工具（如 Webpack、Rollup）默认输出文件名按源码路径原样保留，不会自动标准化大小写；建议 CI 流程中加一步校验脚本：
grep -r "\.png\|\.svg\|\.js" src/ | grep -i "logo" - VSCode 自身不修改插件文件名，所以这个坑只能靠插件作者在开发阶段规避，用户侧无通用修复手段
真正卡住的点往往藏在插件目录里那几行路径拼接代码里，而不是你的网络或设置。别急着重装 VSCode，先打开 ~/.vscode/extensions/ 看一眼文件是不是真在那里。
