根本原因是vscode扩展加载失败时静默降级为齿轮图标，需确保package.json中viewscontainers的location为"sidebar"、图标路径为相对路径、svg单色且无渐变、扩展入口无报错，并通过开发者工具console排查"failed to resolve view container icon"错误。
为什么自定义侧边栏图标总显示齿轮而不是你的SVG
根本原因是 VSCode 在扩展加载失败时会静默降级，用默认齿轮图标兜底，且不报明显错误。这不是图标没配好，而是整个容器注册流程卡在了某一步。
-
package.json中contributes.viewsContainers的location必须是"sidebar"（不是"activitybar"或拼错） - 图标路径必须是扩展包内相对路径，比如
"./icons/my-panel.svg"—— 绝对路径、URL、内置图标名（如"files"）全无效 - SVG 必须单色：只允许
#000或#fff，不能有渐变、fill="currentColor"、滤镜或style标签 - 扩展入口文件（
extension.ts）若抛错（比如registerWebviewPanel调用前就崩溃），图标根本不会被读取
排查最快方式：打开命令面板 → 运行 Developer: Toggle Developer Tools → 切到 Console 标签页，搜 Failed to resolve view container icon。
如何让多个插件图标按功能分组显示在侧边栏
VSCode 本身不支持“文件夹式分组”，但可通过 viewsContainers 的 id + title + icon 组合模拟逻辑分组，关键在于命名和顺序控制。
- 每个容器
id必须唯一且小写，比如"tools-utils"、"tools-format"，后续views中的containerId必须严格匹配 -
title建议用简短功能词（如“工具集”、“格式化”），避免带空格或标点，否则 Activity Bar 显示可能截断 - 图标颜色统一用灰色
#6c7280，它在亮/暗主题下都清晰，比黑/白切换更稳定 - 顺序由
workbench.activityBar.visibleEntries控制：手动列出所有容器 ID，比如["workbench.view.explorer", "tools-utils", "tools-format"]
注意：visibleEntries 里漏掉某个 id，对应图标就彻底消失；顺序错乱会导致图标排列跳动，重启后才生效。
右键拖拽重排图标 vs 编辑 settings.json，哪个更可靠
拖拽看似方便，但只改 workbench.activityBar.visibleEntries 的顺序，且依赖 UI 渲染状态——在远程开发（SSH/WSL）、全屏模式、或某些 UI 扩展启用时容易失效或回滚。
- 右键拖拽后，立刻打开
settings.json查看workbench.activityBar.visibleEntries是否已写入，没写入说明操作未落盘 - 真正跨环境稳定的方案是：先运行
Developer: Generate Default Activity Bar Entries获取当前有效 ID 列表，再手动编辑visibleEntries数组 - 工作区级
.vscode/settings.json会覆盖用户级设置，且无提示——检查是否项目里有同名配置项干扰
拖拽适合临时调整，长期维护或团队同步必须走 JSON 配置，否则协作时布局天天变。
为什么改了 workbench.sideBar.location 还在左边
常见误配是混淆了 sideBar 和 activityBar：前者控制整个侧边栏主体位置（左/右），后者只控制左侧图标栏显隐或偏移。
- 错误写法：
"workbench.activityBar.location": "right"→ 这会让图标栏飘到右边，Explorer 还在左边，界面错乱 - 正确写法：
"workbench.sideBar.location": "right"，值只能是"left"或"right" - 右键菜单 “Move Side Bar to Right” 失效时，90% 是因为点了图标本身而非两个图标之间的空白区域
- macOS 全屏模式下部分版本会忽略该命令，退出全屏再试；Linux 桌面环境可能拦截右键，此时直接改 JSON 最稳
最隐蔽的坑是工作区配置覆盖：哪怕你用户设置写了 "right"，只要项目根目录有 .vscode/settings.json 且含 "left"，就会静默生效——删掉或统一修改它才能真正生效。
