接入已有 Web 项目

确认接入边界#

本指南适用于能构建成静态 HTML、JavaScript 和 CSS 的前端工程。Trove 会在 WebView 中加载这些资源。React、Vue 都可以使用同一套 SDK，不要求采用专用渲染框架。

Trove 不会自动打包或托管 SSR 服务。请导出静态客户端，或把必要的原生、服务端逻辑放入 Backend。不要把密钥或仅原生环境可用的模块放进浏览器构建产物。

获取匹配版本的 SDK#

在已有工程根目录执行接入向导：

cd my-web-app
trove adopt
npm install

按向导选择名称、ID、生产 HTML 路径、包管理器、已有开发/构建脚本与开发地址。上例使用 npm；其他包管理器执行对应 install。adopt 添加 curio.json、匹配的本地 SDK，并更新原 package.json 的 SDK 依赖；保留业务源码、其他依赖与脚本。取消问答不会写入。

已有 Manifest 时直接运行 trove kit 更新套件，再 install。提交 vendor 与锁文件。无需创建临时 starter 来提取 SDK。

检查 Manifest#

向导结束后检查生成的 curio.json。下面是完整的 UI-only 示例，假定你选择 npm 的 dev、build 脚本，并输出到 dist/：

{
  "schemaVersion": 1,
  "id": "dev.example.my-web-app",
  "name": "My Web App",
  "version": "0.1.0",
  "engine": { "trove": ">=0.0.1-alpha.1 <0.0.2" },
  "ui": { "entry": "dist/index.html" },
  "development": {
    "ui": {
      "url": "http://127.0.0.1:5173",
      "command": ["npm", "run", "dev"]
    }
  },
  "build": { "command": ["npm", "run", "build"] },
  "package": { "files": ["dist"] }
}

将 ID、名称、输出路径和命令调整为你的项目配置。ui.entry 是本地生产 HTML 文件；development.ui.url 是开发地址。不要把远程网站 URL 填入 ui.entry。

对齐开发地址与资源路径#

使用 Vite 时，把下面配置合并到已有配置中，保留框架插件：

import { defineConfig } from "vite";

export default defineConfig({
  base: "./",
  server: { host: "127.0.0.1", port: 5173, strictPort: true },
  build: { outDir: "dist" },
});

相对资源路径可以让打包后的入口正确解析 JS 和 CSS。打包后检查图片、字体、动态 import 和页面导航。只有一个 HTML 入口的应用可以使用 hash 路由，避免依赖 HTTP 服务的 history fallback。

如果开发服务已在运行，不要再次启动它，直接连接：

trove dev --no-start-ui --ui-url http://127.0.0.1:5173

同时开发多个工程时，分配不同固定端口，或采用本地开发中的模板动态端口方案。

在界面中连接 Host#

在事件处理或客户端生命周期中调用，展示加载、成功和失败状态：

import { host, TroveError } from "@trove/plugin-sdk";

export async function inspectHost() {
  try {
    return await host.runtime.getHostInfo();
  } catch (error) {
    if (error instanceof TroveError) {
      console.error(error.code, error.message, error.traceId);
    }
    throw error;
  }
}

调用会等待连接就绪；也可显式 await host.ready()。仅导入 SDK 是惰性的。在普通浏览器中使用独立 Mock，不把原生调用失败伪装成成功。

分别验证开发与生产#

1. 在工程中执行 trove check，解决 Manifest 与依赖错误。
2. 执行 trove dev，确认 UI 正常，并获得真实 Host 响应。
3. 停止开发会话，执行 trove pack 和 trove install。
4. 保持开发服务器关闭，打开安装版本，检查路由和资源，再执行原生调用。

开发 URL 可访问不能证明安装包可运行。打包与分发说明文件选择和原生运行时的要求。