快速入门排错

本页用于完整练习的逐层排错。短入门从第一个插件开始；通用故障见常见问题排查。原则：先看第一条报错，每一步只解决一个问题。

固定诊断序列

先想清楚你在哪一层目录——能力工程的命令都在工作区根跑（有 package.json 和 packages.json 那层），单插件工程的命令在插件根跑（有 fh2-plugin.json 那层）：

generate/validate/build/dev 是模板 package.json 里自带的脚本；tsc、test 不一定每个模板都配了，缺了就跳过，别把"Missing script"当成原始故障。哪一步开始失败，问题就在哪一层。构建失败时不要打开本地调试页面——产物都没有，看了也白看。

逐层检查表

阶段	查什么	怎么处理
安装	Node 版本、工具链获取与依赖配置是否完成	对照环境准备；源码从 GitHub 仓库获取，不要猜包名或用第三方转载的地址
生成	清单改了但类型没更新	重跑 `pnpm run generate`；不要手改 `src/generated/`
校验	以第一条 `validate` 报错为准	报错信息会给出文件和字段名，按提示改
构建	入口引了 Vue / 界面引了入口	Vue 组件只放 `src/views/`；入口只做逻辑
激活	宿主 ID 对不对、权限有没有声明	确认扩展点属于当前宿主；处理 `capabilities.get()` 返回 `undefined`
后端	接口名、`pluginId`、权限	用统一入口调用；核对清单 `allowlist`

清单里的典型错误

源清单 fh2-plugin.json 里出现以下字段会被直接拒绝；它们属于前端构建产物，由 build 写入 dist/fh2-plugin.json：

字段	原因
`manifestVersion`、`engines`、`buildInfo`	构建产物专有，工具链在构建时写入
`trusted`、`trustLevel`、`sandbox`	运行方式不是作者可声明的概念，插件无权自报

后端接口 404 / 报错

先确认完整 dev 已启动。build / pack 只生成产物，不启动 HTTP 服务；本地 dev 才提供插件运行时与本地 HTTP 模拟器。首次业务调用推荐用全栈入门的 ctx.apiCall 受管通道，无需填写凭据。

以下无需令牌的回环辅助接口仅在本地调试页面和后端调试服务运行时可用；不要套用到部署环境：

现象	处理
404	工程没有 `backend/` 目录，或启动时用了 `--frontend-only`；改用完整 `pnpm run dev`
连接被拒绝	仅运行了 `build` / `pack`，或 dev 已停止；先启动服务，再按实际监听地址诊断
curl 鉴权失败	直接调用需要插件网关提供的有效插件令牌；业务 API 的 `PLUGIN_API_ORIGIN`、服务选择和鉴权配置按目标环境接入说明设置，直接后端服务的 Bearer 凭据与插件令牌不可互换
`BACKEND_DIST_MISSING`	先修复 `build`，再启动 dev
`HANDLER_NOT_FOUND`（本地）或返回 40006（真实后端）	前端传的 `handler` 名与 `handlers/` 下的文件路径不一致
返回 40006	参数缺失或格式不对（契约错误），检查 `input`
返回 50301	可能是暂时不可用、超时或认不出的脚本错误；平台不自动重发 HTTP 请求。先核对错误分类与写入结果，安全重试须复用稳定业务键

本地正常、真实环境不行

本地调试页面验证模拟交互和调用，不能单独证明公共契约全部正确或真实环境可用。取得允许插件调试的 HTTP 私有化环境、登录及项目权限后，在教程工作区根运行已有预览脚本；FH2_URL 为获授权的完整 HTTP 项目页地址：

只替换本地前端，后端仍用目标环境已安装版本。启用本次 PAC，先在同一 origin 登录并进入项目，再打开调试面板、手填终端本次资源根、校验权限并同意后确认重载；链接不会自动填写来源。当前不支持 HTTPS / 证书路线，详细操作和清理见真实环境预览。

完成标志

第一条报错已定位到某一层（安装 / 生成 / 校验 / 构建 / 激活 / 后端）。

generate、validate、build 通过；模板提供 tsc / test 时也通过，能力工程可单独进入前端插件目录检查类型。

本地调试页面中核心交互可复现。

停用插件后页面无残留（没有僵尸按钮、空面板）。

固定诊断序列#

逐层检查表#

清单里的典型错误#

后端接口 404 / 报错#