环境准备

本页介绍插件化开发者工具的完整环境准备，适用于 SDK / 工具链 1.0.0：在源码目录安装依赖、构建工具，再在源码目录之外创建插件工程。全局注册是可选步骤，不是开发前提；只想先看到面板可走快速入门，需要 AI 协助可走AI 开发 Skill。

准备开发者工具

仓库：github.com/dji-sdk/FlightHub-2-Plugin；git clone 或下载 ZIP 都可以。

取得插件开发工具完整源码后，解压或 clone 到长期固定的目录。

SDK 在 packages/fh2-plugin-sdk/，工具链在 packages/fh2-plugin-toolchain/，Skill 在 skills/fh2-plugin-dev/。SDK 与开发工具一起下载，不需要另装同名公共 npm 包。 下文先构建这份源码，创建工程时自动接入本地 SDK 和工具链。

使用其他版本时，取得与目标司空版本配套的源码和固定 tag/commit 或归档身份；保留其许可说明，不用同名 npm 包替代。

取得源码后，确认交付内容包含：

插件 SDK、工具链及相互匹配的版本。

根目录的 README.md、package.json、pnpm-workspace.yaml、pnpm-lock.yaml、public-distribution.json 和许可说明。

packages/fh2-plugin-sdk/、packages/fh2-plugin-toolchain/ 和 examples/，保留交付时的目录结构。

工具链配套的 developer-runtime/ 开发者运行数据和 runtime-assets/mock-host/ 预构建本地调试资源。

缺少来源、固定版本或配套文件时，请先到仓库 Issue 确认。源码归档不需要 .git 或 git init；解压目录名可以不同，但不能拆开 SDK、工具链和配套资源。

本文用 fh2-plugin-sdk 表示插件开发 SDK，用 fh2-plugin-toolchain 表示提供 fh2-plugin 命令的工具链。实际导入路径、依赖名称和版本沿用生成工程；不要据此寻找同名公共 npm 包、重命名依赖或手写路径别名。

需要装什么

软件	版本要求	说明
操作系统 / 终端	以所选发行的支持矩阵为准	下文按 POSIX shell 写命令，Windows 转换见下文；命令语法可转换不代表所有系统组合已验收
Node.js	最低 20.19；推荐 22 LTS 及以上	用 `node --version` 确认；其他版本与系统组合以所选发行说明为准
开发者工具根目录包管理器	pnpm 10，由 Corepack 按固定版本（10.15.0）自动准备	通常无需手动安装；不要与其他 pnpm 版本混用，工程包管理器另选
插件工程包管理器	pnpm、npm 或 Yarn Classic 1.22.x	创建工程时选择一种，之后保持一致；不改变开发者工具根目录必须使用 pnpm 的要求
现代浏览器	Chrome / Edge	打开本地调试页面

终端说明：手册的多行命令示例使用 POSIX shell 语法（export 设置变量、\ 续行）。Windows 用户推荐在 Git Bash（Git for Windows 自带）中执行这些示例，或按 PowerShell 等价方式转换：export FH2_TOOLS="..." 对应 $env:FH2_TOOLS = "..."（cmd 为 set FH2_TOOLS=...），行尾 \ 续行对应 PowerShell 的反引号或改写为单行。corepack enable 在 Windows 默认安装位置（Program Files）需要管理员终端；非管理员可改用 corepack enable --install-directory "$env:USERPROFILE\.local\bin" 并把该目录加入 Path。

安装工具链

把源码保存到长期固定的位置，与插件工程分开。在编辑器中打开解压后的源码文件夹，再打开终端。
确认终端当前目录里能看到 package.json、pnpm-lock.yaml 和 public-distribution.json，然后执行：

Node 必须满足 >=20.19；在开发者工具根目录执行 pnpm --version 应显示 10.15.0（Corepack 按 packageManager 自动选择）。不要看到版本错误还继续安装。
若 pnpm 不存在或解析到其他版本，但已有 Corepack，可只创建本次工具用的 shim（命令入口）：

这不删除旧 pnpm，也不修改全局 npm 配置；export PATH 只影响当前终端。
Corepack 不存在时，先按 Node.js 官方说明安装它，或用 npx -y pnpm@10.15.0。
新开终端后要重新检查 Node/pnpm，重新设置 FH2_TOOLS；不要假定旧终端的变量仍在。

版本正确后，按顺序安装和构建：

pnpm install --frozen-lockfile 使用随源码交付的锁文件安装依赖；若锁文件不匹配，保留第一条错误并到仓库 Issue 反馈，不删除锁文件或去掉 frozen 约束。FH2 SDK 和工具链来自这份源码，不需要公共 FH2 npm 安装或完整 Contract 包；第三方依赖仍需按你已有的 registry 配置获取。

上面的 fh2-plugin() 是当前 Bash/Zsh 终端里的短命令，不是全局安装。后续教程可直接输入
fh2-plugin create；新终端需要重新定义。工程创建并安装后，使用 pnpm exec fh2-plugin
或工程的 pnpm run ... 脚本。

pnpm build:tooling 构建 SDK、工具链和 Web IDE，校验并装配本地调试资源；不会注册全局 CLI、
发布 npm 包或安装开发 Skill。这些命令在开发者工具根目录执行，不是在插件工程里执行。

帮助输出应包含子命令；create --help 应列出 capability-fullstack、frontend-basic、backend-basic 三个模板。帮助能打开只说明 CLI 能启动，不代表完整教程或目标环境已经验证。

可选：注册独立 CLI 目录

只用上面的短命令即可开发。如果想让命令脱离 shell 函数，先阅读注册脚本帮助：

使用独立 prefix：在类 Unix 终端中选择一个单独的可写注册目录，将它的 bin 加到当前终端的 PATH 前面；不会修改原 prefix 的注册。Windows 上独立 prefix 的命令 shim 生成在 prefix 根目录（不是 bin），把 prefix 本身加入 Path：

不注册全局命令：直接调用已经构建的源码 bin。后续创建命令中的 fh2-plugin 也用这一入口替代，参数不变：

不要改用 dist/cli.js；bin 入口保留源码定位行为。确实需要替换已识别的同名全局注册时，先阅读注册脚本帮助并确认影响，再使用其 --replace-existing 选项。

插件工程包管理器

下面的命令只用于新建或已有插件工程，不替代开发者工具根目录的 pnpm 初始化。创建时的 --install 会使用所选包管理器安装工程依赖；之后在工程根只用同一列，不混用锁文件：

动作（在插件工程中）	pnpm	Yarn Classic	npm
安装已有工程依赖	`pnpm install`	`yarn install`	`npm install`
调用工程本地 CLI	`pnpm exec fh2-plugin --help`	`yarn run fh2-plugin --help`	`npm exec --no -- fh2-plugin --help`
执行工程构建脚本	`pnpm run build`	`yarn run build`	`npm run build`
创建时的参数	`--package-manager pnpm`	`--package-manager yarn`	`--package-manager npm`

需要可用的端口

端口	用途
5175	本地调试页面（默认）
5176	驾驶舱高保真本地调试页面
4317	HTTP 目标预览的本机代理；不表示宿主已加载插件

端口被占用时，在插件工程里换端口启动（做法见本地开发）。

真实预览只支持 HTTP PAC；需要获授权的目标宿主、同源登录和项目权限，并手填本次资源根、校验及同意后加载。不需要本地证书，完整步骤见真实环境预览。

验证

切换到源码目录之外的工程父目录。以下沿用教程中的 $HOME/fh2-plugin-dev，FH2_TOOLS 保持指向已经初始化的固定源码；exp_source_check 必须不存在或为空，已有工程不要删除，换一个目录名即可。使用当前终端短命令的示例：

向导选择 0（完整能力），目录填写 exp_source_check，名称采用默认，包管理器选 pnpm，
立即安装选 是。创建完成后执行：

预期在 $HOME/fh2-plugin-dev/exp_source_check/ 生成工作区根的 package.json、packages.json，内部 exp_source_check/ 含 capabilities.json、frontend/、backend/ 和 mock/。选择立即安装会安装依赖并执行类型复验，随后在新工作区根检查本地 CLI、生成和校验。

由源码 bin 调用的向导会自动定位本地 SDK 和工具链，生成的依赖及相应覆盖使用 file: 路径。
只有使用其他来源的 CLI 时才需显式指定 --platform-root "$FH2_TOOLS"。
保留生成工程的实际依赖名、导入路径和配置，不手写模块别名，也不另装完整 Contract。
通过这些检查后再继续前端、后端或全栈教程；它们不代替教程中的业务运行验证。

build 和 pack 只生成交付产物，不启动接口服务。dev 启动本地调试页面；工程包含后端且未选择仅前端模式时，还会启动用于接口调试的本地 HTTP 模拟器。它不是部署环境的真实网关。目标环境接口诊断需要另行取得服务入口和有效凭据，不能从构建成功推断接口已可访问。

保留源码与版本

长期保留固定源码目录，记录所用 tag/commit 或归档身份，以及 public-distribution.json 中的版本和摘要。不要只记录“最新版”或一个目录名。

工程内优先使用本地 CLI 和工程脚本。全局 CLI 与某个工程的本地 CLI 可以来自不同源码版本；重新构建或 link 全局版本不会自动刷新已经复制到工程里的依赖。

移动源码目录或升级前，先取得并构建固定的新版本源码，保留旧副本和现有改动。核对受影响工程中的本地 file: 路径及相应覆盖，再按工程原有包管理器重新安装、生成、校验和构建；不会自动升级所有工程。

在源码根可用 pnpm check:source 检查固定运行数据和预构建资源。缺失或不匹配时从同一版本恢复，不手改生成数据、清单或摘要；这项检查不代表完整教程通过或允许公开发布。

在当前源码根执行 pnpm unlink:toolchain 只解除属于这份源码的全局注册，不删除业务工程，也不会自动恢复此前被替换的安装。独立 prefix 的注册需按注册脚本帮助用同一 prefix 解除。

常见问题

现象	原因与处理
`Unsupported engine`	检查 Node.js 是否达到最低 20.19，并确认没有混用其他 pnpm 版本；切换后重新安装依赖
frozen 安装失败	检查 pnpm 10.15.0 和同版源码锁文件，保留第一条错误；不要删除锁文件或去掉 frozen
`fh2-plugin: command not found`	检查本次注册目录是否在 `PATH`；也可直接调用已构建的源码 bin。工程内用所选包管理器的本地 CLI
`FH2_LINK_CONFLICT`	已有其他全局注册，使用独立 prefix 或直接调用源码 bin；不要静默覆盖
安装报 401 / 403	检查已配置的第三方依赖来源及其访问权限；开发者工具不要求 FH2 registry 登录，凭据由你按提供方流程处理
`EADDRINUSE`（端口占用）	换端口启动，或关掉占用端口的进程

下一步：第一个前端插件。

准备开发者工具#

需要装什么#

安装工具链#

可选：注册独立 CLI 目录#

插件工程包管理器#

需要可用的端口#

验证#

保留源码与版本#

常见问题#