ambleloft定义插件图标
让用户在侧边栏与扩展管理中认出你的应用。图标是包内资源，需要同时完成声明和复制。
实践指南
完成后：安装后看到插件图标，并检查深浅主题表现。
前置条件：按本页具体步骤准备所需文件与工具；学习路线中的上一页不自动构成依赖。
本页内容
01准备 PNG 资源
创建 assets/icon.png，推荐 128×128、透明背景、约 10% 留白。必须是静态 PNG、小写 .png 后缀、正方形，边长 16–512 像素且文件不超过 64 KiB。侧边栏以 18×18 CSS 像素显示，细线和文字容易丢失。
02修改 extension.json
将 icon 加到现有清单顶层，保留其他字段。下面是合并片段，不是完整清单。路径相对扩展包根目录，不支持网络 URL、data URL、绝对路径、.. 或符号链接。
extension.json · merge fragment
"icon": "assets/icon.png"03复制到构建产物
在脚手架 build.cjs 的异步函数中、output 创建之后，加入以下代码。root、output、fs、path 均已由模板定义。运行 build 后检查 dist/package/assets/icon.png 存在，再 validate 和 pack。
build.cjs · insert inside async function
await fs.cp(path.join(root, 'assets'),
path.join(output, 'assets'), { recursive: true });04深浅主题双图标
如需适配主题，把字符串换成下面对象，并复制两份资源。light 和 dark 必须同时提供；宿主按实际主题选择，不对图片重新染色。不支持运行时 setIcon。
extension.json · alternative fragment
"icon": {
"light": "assets/icon-light.png",
"dark": "assets/icon-dark.png"
}05验收与排错
安装后切换深浅主题检查侧边栏与扩展管理。没有声明图标时显示默认图标；声明了无效资源会导致安装校验失败。先检查打包路径、PNG 格式、大小与尺寸，再排查宿主版本。
打开完整可运行案例检查结果与排错
安装后看到插件图标，并检查深浅主题表现。
按本页的验证步骤核对实际结果。涉及业务服务时，分别检查界面提交、工具回执与服务端记录。
打开错误代码与排错 →