常见问题

按「开发调试 / 权限与调用 / 界面与主题 / 打包与发布」四类整理。没找到答案的问题，欢迎通过关于页面的联系方式反馈。

开发调试

改了代码，宿主里看到的还是旧界面？

九成是 dev server 的问题。宿主只在 dev server 可达时才直连它，探测失败会静默回退加载本地 dist 产物：

1. 确认 pnpm dev 在跑，且端口与 development.main 一致（建议 vite 配 strictPort: true，防止 vite 端口被占后自己换端口）。
2. 在浏览器里直接开 http://localhost:<端口> 验证页面本身能访问。
3. 确认插件在「插件开发者」里处于运行调试登记态（宿主重启后登记失效，重新点一次「运行调试」）。
4. 如果确实在加载旧 dist，重新 pnpm build 更新产物。

development.main 可以填局域网地址方便真机调试吗？

不行。出于安全考虑，development.main 只允许 localhost / 127.0.0.1 / [::1] 的 http(s) 地址，宿主会拒绝登记远程页面。

怎么在插件里打印日志排查？

普通 console.log 在 WebView 开发者工具里看（调试态宿主可右键插件页面打开 DevTools）；需要留痕的日志走宿主日志域 udhold.log，可在宿主的调试日志面板统一查看。

插件页面一打开就白屏？

常见原因：构建产物路径不对（vite 没配 base: './'，产物用了绝对路径 /assets/...，在宿主 asset 协议下 404）；或 dist 字段指错了入口文件。免构建插件则检查 index.html 是否在插件根目录。

dev server 启动很慢，宿主会不会超时？

「运行调试」轮询端口就绪有 90 秒超时，覆盖正常 pnpm install + 启动的时间。首次安装依赖较慢属正常，后续热启动都在秒级。

权限与调用

调用 API 返回 code 403 / PERMISSION_DENIED？

permissions 没声明或写错了。对照排查：

• 声明是前缀匹配：files.list 精确放行一个方法，files.* 放行整个域。
• 拼写以能力目录为准：方法路径必须与 API 文档一致（域.方法，如 ai.models.list）。
• 改了 plugin.json 后要重开插件让新权限生效。
• 存储类（db / dbStorage）、路由、生命周期等基础能力免声明；文件、剪贴板历史、AI、登录态等敏感域必须声明。

调用其他插件（router.push / plugin.run）被拒？

跨插件调用要在 plugin.json 的 plugins 数组里登记目标插件名："plugins": ["files", "calculator"]；声明 "*" 放行全部（审核高风险，不推荐）。打开自己豁免白名单。

方法调用没有抛错但拿不到数据？

宿主方法统一返回 IpcResult 信封，失败也是正常 resolve。要检查 res.code !== 0（失败）与 res.success === false（业务分歧，非错误）两个分支，不能只 try/catch。

插件数据存在哪？卸载会清掉吗？

数据落在用户数据目录 plugin-storage/<插件名>/ 下，各插件自动隔离，互不可见。卸载插件默认连数据一起清空；用户在插件中心手动卸载时可选择保留。禁用则完全保留数据，随时恢复。

界面与主题

插件没有跟随宿主的明暗主题？

工程型插件检查入口 main.ts 是否调用了 setupThemeSync()（来自 @udhold/udhold-ui/utils），并确认引入了 @udhold/udhold-ui/styles/global.css。免构建插件没有这套工具，需要监听宿主事件 udhold.onThemeChange 手动切换样式。完整机制见主题与明暗模式。

图标显示不出来（i-z-xxx 类）？

i-z-* 图标类来自插件自己的本地 SVG 图标集，检查：

1. uno.config.ts 配了 presetIcons 且用 FileSystemIconLoader 把 src/assets/icons 注册为 z 集合；
2. SVG 文件名与类名一致（i-z-back 对应 back.svg）；
3. 使用 DetailPanel 组件的插件，图标集里必须有 back.svg（组件内部依赖它）。

配置方法见图标体系。

Message 消息弹不出来？

Message 与 ConfirmDialog 是「挂载一次、全局调用」的组件，确认根组件模板里挂了 <Message :items="messageState" ... />（useMessage() 返回的状态要接上），否则 message.success(...) 不会有任何显示。

用 React / 原生 JS 能开发吗？

可以。插件就是 Web 页面，框架不限（官方的 JSON Tools 就是 React 工程）。注意 @udhold/udhold-ui 的 Vue 组件不能直接用于 React，但其设计令牌与全局样式（global.css）和工具函数（setupThemeSync 等）是框架无关的，照常引入即可。

打包与发布

打包后的插件缺文件 / 样式丢了？

打包严格按 plugin.json 的 build 字段收录：["dist"] 就只有 dist 目录。检查：

• 是否先执行了 pnpm build（打的是当时的旧 dist）；
• 插件根目录的 plugin.json 与 logo.png 由打包器固定收进包根，无需进 build 数组；src/ 里引用的其他静态资源要随构建一起进 dist（放 src/assets 或 Vite public/ 均可）；
• 需要额外收录 services[].entry 等根目录文件时，把它们加进 build 数组。

上传市场后在哪里看审核状态？

在「插件开发者」的发布相关页面可以查看已上传版本与审核状态；审核未通过会附原因（多数是权限声明与实际功能不符）。

用户怎么收到新版本？

改 plugin.json 的 version（semver，比较大小决定是否更新）→ 构建打包 → 上传市场。已安装用户打开插件时宿主自动检查更新并静默完成安装，无需用户操作。

能不能先小范围发给别人测试？

可以，不走市场：打包 zip 直接发给对方，在插件中心「本地安装」导入即可。市场发布时也可以先选「测试」状态灰度，验证无误再转「正式」。

想让插件开机自启怎么做？

两种方式：纯后台场景在 plugin.json 声明 "startup": "background"（宿主启动完成后拉起无头实例，启动形式由插件自己编排）；带服务进程的插件把服务的 startup 设为 "host"（随宿主启动，不创建界面）。