hubspot-app-builder

HubSpot App Builder（Platform 2026.03）

本技能介绍如何基于最新开发者平台（版本 2026.03）开发完整的 HubSpot 应用，涵盖项目创建、配置、UI 扩展、无服务器函数、Agent 工具、Webhooks 和分发。

Platform version 2026.03 于 2026 年 3 月 30 日发布（已在 2026 年 4 月 14 日的 Spring 2026 Spotlight 中确认正式发布）。此版本重新为应用提供完整的无服务器函数支持（包括静态身份验证应用），为 Breeze Agents 引入 Agent 工具，将 App Homes 扩展为多页面 App Pages，并通过 npm workspaces 添加代码共享功能。此前的版本 2025.2 现已处于“Supported”状态。

先决条件

• HubSpot CLI v8.3.0+：npm install -g @hubspot/cli@latest
• 身份验证：hs account auth
• Node.js 22+（最低版本在 2025.2 中提升至 v22，并延续至 2026.03；2025.1 中为 v20）
• HubSpot 开发者帐户
• 生产环境中的无服务器函数需要 Enterprise 订阅（开发者测试帐户无需订阅）

项目设置工作流

1. 创建项目

hs project create

按照 CLI 提示进行配置：

• 分发方式：marketplace（用于在 App Marketplace 上架）或 private（用于指定帐户）
• 身份验证：oauth（多个帐户）或 static（单个帐户）
• 功能：从 card、settings、pages、app-function、serverless-function、webhooks、workflow-action 中选择

稍后添加功能：

hs project add

2. 项目文件结构

my-project-folder/
├── hsproject.json                    # Must include "platformVersion": "2026.03"
├── packages/                         # Shared code (npm workspaces, optional)
│   └── shared-utils/
│       ├── index.ts
│       └── package.json
└── src/
    └── app/
        ├── app-hsmeta.json          # Top-level app config (required)
        ├── cards/                    # UI extension cards
        │   ├── MyCard.jsx
        │   ├── my-card-hsmeta.json
        │   └── package.json
        ├── pages/                    # App Pages (multi-page, formerly App Homes)
        │   ├── HomePage.jsx
        │   ├── home-page-hsmeta.json
        │   ├── DetailPage.jsx
        │   ├── detail-page-hsmeta.json
        │   └── package.json
        ├── settings/                 # App settings page
        │   ├── Settings.tsx
        │   ├── settings-hsmeta.json
        │   └── package.json
        ├── functions/                # Serverless functions (2026.03 format)
        │   ├── myFunction.js
        │   ├── myFunction-hsmeta.json   # Individual config per function
        │   └── package.json
        ├── app-events/               # App events (open beta)
        │   └── my-event-hsmeta.json
        ├── app-objects/              # App objects (open beta)
        │   └── my-object-hsmeta.json
        ├── webhooks/                 # Webhook subscriptions
        │   └── webhooks-hsmeta.json
        └── workflow-actions/         # Custom workflow actions / Agent tools
            └── custom-action-hsmeta.json

3. 配置 app-hsmeta.json

{
  "uid": "my_app_uid",
  "type": "app",
  "config": {
    "name": "My App",
    "description": "App description for installing users.",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": ["crm.objects.contacts.read"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.example.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "[email protected]",
      "documentationUrl": "https://example.com/docs"
    }
  }
}

关键规则：

• uid 在项目中必须全局唯一（最多 64 个字符，可使用字母数字字符、_、-、.）
• type 必须与父文件夹名称（app）一致
• 单帐户私有应用使用 static 身份验证，并移除 redirectUrls
• 至少包含一个 read 范围（例如 crm.objects.contacts.read）

4. 上传并部署

hs project upload          # Upload and trigger a build
hs project open            # Open project in HubSpot browser
hs project dev             # Start local dev server with hot reload
hs project install-deps    # Install package.json dependencies

5. 安装应用

上传后，通过 HubSpot UI 安装：

• 前往 Development > Projects > [Project Name] > [App UID]
• 点击 Distribution 选项卡
• 对于测试帐户：点击 Add test install(s)
• 对于标准帐户：点击 Install now

UI 扩展

所有 UI 扩展都使用相同的结构：一个 *-hsmeta.json 配置文件和一个 React 组件文件（.jsx 或 .tsx）。

App 卡片配置（cards/*-hsmeta.json）

{
  "uid": "my-card",
  "type": "card",
  "config": {
    "name": "My Card",
    "description": "Card description.",
    "location": "crm.record.tab",
    "entrypoint": "/app/cards/MyCard.jsx",
    "objectTypes": ["contacts"]
  }
}

支持的位置：

位置	值	备注
CRM 中间栏	crm.record.tab	最常见；支持自定义选项卡
CRM 右侧边栏	crm.record.sidebar	此处不支持 CRM 数据组件
CRM 预览面板	crm.preview	可预览 CRM 中的各类记录
帮助台边栏	helpdesk.sidebar	需要 tickets 范围
App Pages（以前称为 App Home）	home	多页面全屏体验；使用 PageRoutes 和 PageLink 进行导航
应用设置页面	settings	HubSpot 设置中的配置 UI

支持的 objectTypes： contacts、companies、deals、tickets、orders、carts、p_customObjectName、app_object_uid

React 组件模式

import React from "react";
import { hubspot, Text, Button, Flex } from "@hubspot/ui-extensions";

// Required: register extension with HubSpot
hubspot.extend(({ context, actions }) => (
  <MyCard context={context} addAlert={actions.addAlert} />
));

const MyCard = ({ context, addAlert }) => {
  return (
    <Flex direction="column" gap="medium">
      <Text>Hello, {context.user.firstName}!</Text>
      <Button onClick={() => addAlert({ type: "success", title: "Done", message: "Action completed" })}>
        Click me
      </Button>
    </Flex>
  );
};

SDK Hooks（推荐方式）

import { hubspot, Button, useExtensionApi } from "@hubspot/ui-extensions";
import { useCrmProperties } from "@hubspot/ui-extensions/crm";

hubspot.extend<'crm.record.tab'>(() => <MyCard />);

const MyCard = () => {
  // Access both context and actions
  const { context, actions } = useExtensionApi<'crm.record.tab'>();

  // Fetch CRM properties from the current record
  const { properties, isLoading } = useCrmProperties(["firstname", "lastname", "email"]);

  if (isLoading) return <Text>Loading...</Text>;

  return (
    <Button onClick={() => actions.addAlert({ message: `Hello ${properties.firstname}!` })}>
      Say Hello
    </Button>
  );
};

可用的 hooks：

• useExtensionApi<location>() — 同时访问上下文和操作
• useExtensionContext<location>() — 仅访问上下文
• useExtensionActions<location>() — 仅访问操作
• useCrmProperties(["prop1", "prop2"]) — 来自 @hubspot/ui-extensions/crm
• useAssociations({ toObjectType, properties, pageLength }) — 来自 @hubspot/ui-extensions/crm

获取外部数据

import { hubspot } from "@hubspot/ui-extensions";

// GET
const response = await hubspot.fetch("https://api.example.com/data", {
  method: "GET",
  timeout: 5000,
});
const data = await response.json();

// POST — body is a plain object, not JSON.stringify()
const response = await hubspot.fetch("https://api.example.com/data", {
  method: "POST",
  body: { key: "value" },
});

与原生 fetch 的主要区别：

• body 是普通对象——不要使用 JSON.stringify()，也不要手动设置 Content-Type
• 自定义标头仅支持 Authorization
• URL 必须列在 permittedUrls.fetch 中；不允许使用 localhost（请使用代理）
• HubSpot 会在每个请求中追加 userId、portalId、userEmail、appId 查询参数
• 最多 20 个并发请求；超时时间为 15s；负载上限为 1MB

你的后端必须验证每个传入请求中的 X-HubSpot-Signature-v3——请参阅 references/signature-validation.md。

完整指南（代理设置、Authorization 标头模式、本地开发签名、监控）请参阅 references/fetching-data.md。

无服务器函数（2026.03 格式）

平台版本 2026.03 重新为应用提供完整的无服务器函数支持，包括使用静态身份验证的应用。无服务器函数在 HubSpot 的基础设施中执行服务端 JavaScript，无需外部服务。

Important: 2026.03 使用新的、每个函数各自的 -hsmeta.json 配置文件，取代 2025.1 使用的单个 serverless.json。每个函数在 src/app/functions/ 中都有自己的配置文件。

无服务器函数类型

• 私有（应用）函数——由 App Cards、App Pages 和 App Settings 中的 UI 扩展调用的内部函数。需要 Enterprise 订阅或免费的开发者测试账户。
• 公共端点函数——可通过 HTTP 访问的端点。需要 Content Hub Enterprise。开发者测试账户不支持此功能。

目录结构（2026.03）

src/app/functions/
├── myFunction.js
├── myFunction-hsmeta.json    # Individual config per function
└── package.json

这取代了 2025.1 的结构；该版本使用嵌套的 .functions 文件夹和单个 serverless.json。

配置（myFunction-hsmeta.json）

私有应用函数（无公共端点）：

{
  "uid": "myFunction",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/myFunction.js",
    "secretKeys": ["my_api_key"]
  }
}

带公共端点的应用函数：

{
  "uid": "myPublicFunction",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/myPublicFunction.js",
    "secretKeys": ["my_api_key"],
    "endpoint": {
      "path": "my-endpoint",
      "method": ["GET", "POST"]
    }
  }
}

无服务器函数模式

// myFunction.js
const hubspot = require("@hubspot/api-client");

exports.main = async (context = {}) => {
  const hubspotClient = new hubspot.Client({
    accessToken: process.env.PRIVATE_APP_ACCESS_TOKEN,
  });

  try {
    const res = await hubspotClient.crm.contacts.basicApi.getPage();
    return res;
  } catch (err) {
    console.error(err);
    return err;
  }
};

重要说明

• 使用 process.env 获取访问令牌（而不是 context.secrets）
• 必须使用 Async/await（不再支持回调）
• 日志大小最高为 256KB，执行顺序有保证
• 使用 hs secret add CLI 命令管理机密
• 支持 NPM 包
• 生产环境需要 Enterprise 订阅（测试账户无需订阅）
• 函数现在可以在开发者测试账户中运行，以便在投入生产前更安全地迭代

将无服务器函数迁移到 2026.03

迁移路径取决于你当前使用的版本：

从 2025.2 迁移：

1. 在 hsproject.json 中，将 platformVersion 从 "2025.2" 更新为 "2026.03"
2. 运行 hs project upload

从 2025.1、2023.2 或 2023.1 迁移：

1. 在项目目录中运行 hs project migrate 并按照提示操作

从旧版公共应用（非基于项目）：

1. 运行 hs app migrate 并按照提示操作

重要迁移说明：

• 必须使用 hs secret add 将旧 serverless.json 中的环境变量重新添加为机密
• 旧的单一配置文件 serverless.json 已由 src/app/functions/ 中每个函数各自的 -hsmeta.json 文件取代

Warning: 将旧版私有或公共应用迁移到 2026.03 后无法撤销——你无法降级回旧版本。

Agent 工具（2026.03 新增）

Agent 工具是增强型自定义工作流操作，HubSpot AI Agent（Breeze Agents）可以调用这些工具，代表用户执行任务。它们使用 Developer Projects 框架构建。

Agent 工具的工作方式

• 在项目中构建为增强型 workflowAction 类型
• 分发前必须提交审核
• 获批后，客户可通过你的应用列表和 Breeze Agents 使用这些工具
• Marketplace 中的应用无法部署未经批准的 Agent 工具——工具通过审核前，部署都会失败

列表要求

提供 Agent 工具的应用必须遵守 Agent 工具列表要求。

如需了解更多详情，请参阅 Agent 工具概览。

使用 npm Workspaces 共享代码（2026.03 新增）

现在，你可以在单个项目中使用 npm workspaces，在多个 UI 扩展（应用卡片、设置页面、应用页面）之间共享代码。

设置

在扩展旁创建共享包：

my-project-folder/
├── packages/
│   └── shared-utils/
│       ├── index.ts
│       └── package.json
└── src/
    └── app/
        ├── cards/
        │   └── package.json     # declares shared-utils as dependency
        └── pages/
            └── package.json     # declares shared-utils as dependency

每个扩展的 package.json 都引用共享包：

{
  "dependencies": {
    "shared-utils": "*"
  }
}

安装

运行 hs project dev 或 hs project upload 时，系统会自动安装共享包；也可以手动安装：

hs project install-deps

详情请参阅 使用 npm workspaces 共享代码。

Developer MCP 服务（正式发布）

本地 HubSpot Developer MCP 服务现已正式发布，可通过 AI 驱动的代码编辑器（Claude Code、Cursor、VS Code 等）进行应用和 CMS 开发。

设置

hs mcp setup

需要 HubSpot CLI v8.2.0+。可用工具包括：create-project、add-feature-to-project、upload-project、deploy-project、validate-project、search-docs、fetch-doc、get-build-status、get-build-logs 等。

如需查看完整工具列表和设置说明，请参阅 Developer MCP 服务文档。

可用 UI 组件

从 @hubspot/ui-extensions 导入：

• 布局：Flex、Box、Divider、Grid、AutoGrid、Spacer、Inline
• 文本/显示：Text、Heading、Image、Link、Icon、Illustration
• 输入：Input、TextArea、Select、MultiSelect、Checkbox、RadioButton、DateInput、NumberInput、CurrencyInput、SearchInput、StepperInput、Toggle、ToggleGroup
• 操作：Button、LoadingButton、IconButton、ButtonRow
• 反馈：Alert、LoadingSpinner、Tag、StatusTag、Badge、Tooltip、ProgressBar、EmptyState、ErrorState
• 覆盖层：Modal、ModalBody、ModalFooter、Panel、PanelBody、PanelFooter、Dropdown
• 数据：Table、TableHead、TableBody、TableRow、TableCell、DescriptionList、Statistics、ScoreCircle
• 导航：Tabs、StepIndicator、Accordion
• 图表：BarChart、LineChart
• 容器：Tile
• 表单：Form、FormField
• 列表：List

从 @hubspot/ui-extensions/crm 导入：

• CRM 数据：CrmPropertyList、CrmAssociationTable、CrmAssociationPivot、CrmAssociationPropertyList、CrmAssociationStageTracker、CrmDataHighlight、CrmReport、CrmStageTracker、CrmStatistics
• CRM 操作：CrmActionButton、CrmActionLink、CrmCardActions

Webhook 配置

创建 src/app/webhooks/webhooks-hsmeta.json：

{
  "uid": "my-webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://api.example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "contact",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "email",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

新格式事件（object.*）使用 crmObjects。经典类型（如 contact.creation）使用 legacyCrmObjects。contact.privacyDeletion 和 conversation.* 使用 hubEvents。

签名验证（必需）

HubSpot 会使用 X-HubSpot-Signature-v3 对所有出站请求进行签名：

• Webhook 投递 — HubSpot 会将事件负载 POST 到你的 targetUrl
• 卡片/设置页面获取 — UI 扩展中的任何 hubspot.fetch() 调用都会经 HubSpot 代理并由其签名

这两种情况都必须使用 @hubspot/api-client 中的 Signature.isValid() 以相同方式进行验证。完整实现请参阅 references/signature-validation.md。

UI 扩展的 package.json

{
  "name": "my-card",
  "version": "0.1.0",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}

安装：hs project install-deps

分发与身份验证摘要

分发方式	身份验证类型	安装限制
private	static	1 个标准账户 + 10 个测试账户
private	oauth	最多 10 个允许名单中的账户
marketplace	oauth	上架前 25 个；上架后不限

应用市场上架

提交到 HubSpot App Marketplace 前，应用必须满足以下关键要求：

技术最低要求：

• OAuth 是唯一的授权方式——不得使用 API 密钥或私有应用令牌
• 过去 30 天内，至少有 3 个活跃安装来自无关联账户，并产生过经 OAuth 身份验证的 API 活动
• 仅请求应用实际使用的权限范围；所有请求的权限范围都必须列在 共享数据 表格中
• 必须运行于受支持的平台版本（目前为 2025.2+，建议使用 2026.03）
• 通过认证的应用必须使用受支持的基于日期的 API 版本
• 新上架或认证的应用不得使用经典 CRM 卡片（必须在 2026 年 10 月 31 日前迁移到 App Cards）
• Agent 工具属于可审核范围——工具通过审核并符合Agent 工具上架要求前，部署会失败

上架内容：

• 内容必须针对具体集成，而非通用产品营销内容
• 所有 URL 都必须有效、可公开访问且不超过 250 个字符——提交前请将 HubSpot Crawler 添加到网站允许名单
• 必须包含：设置文档、安装按钮 URL、支持资源、服务条款、隐私政策和定价（必须与网站完全一致）
• 如果对同一对象同时请求读取和写入权限范围，必须在 共享数据 中声明双向同步

应用卡片（使用 UI 扩展时）：

• 卡片名称或图标不得使用 HubSpot 品牌名称
• 每个界面只能有一个主按钮；破坏性按钮必须使用破坏性样式
• 不得访问或显示敏感数据

**审核流程：**初次审核在 10 个工作日内完成；完整流程最长需要 60 天。一次只能有一个应用处于审核中。

完整的要求清单请参阅 references/marketplace-listing.md。

本地开发

hs project dev            # Starts dev server with hot reload

启动后，测试账户中会显示本地开发主页，其中列出活跃的开发会话。.jsx/.tsx 文件的更改会自动重新加载。

注意（Chrome 142+）：首次启动时，请在 app.hubspot.com 弹出的窗口中允许本地网络访问。

调试

在 HubSpot 中查看日志：开发 > 监控 > 日志 > UI 扩展。

在代码中使用日志记录器：

import { logger } from "@hubspot/ui-extensions";
logger.info("Info message");
logger.debug("Debug message");
logger.warn("Warning message");
logger.error("Error message");

其他资源

参考文件

如需了解详细配置和模式，请参阅：

• references/app-configuration.md — 完整的 app-hsmeta.json 架构、身份验证类型
• references/scopes.md — 按类别分组的所有可用 OAuth 权限范围（CRM、CMS、设置、营销等）
• references/ui-extensions-sdk.md — SDK 钩子、上下文字段、操作 API
• references/fetching-data.md — hubspot.fetch() 完整指南：与原生 fetch 的区别、限制、自动查询参数、Authorization 标头模式、本地开发代理、签名验证
• references/ui-components.md — 所有 UI 组件及示例
• references/features.md — 应用事件、应用对象（公开 Beta）、设置页面、主页
• references/signature-validation.md — Webhook 以及卡片/设置页面 fetch 端点的完整签名验证实现
• references/marketplace-listing.md — App Marketplace 完整上架要求、品牌规则、应用卡片标准和审核流程

官方文档

• 创建应用
• 应用配置参考
• 在 HubSpot 中管理应用
• UI 扩展概览
• 应用卡片参考
• UI 扩展 SDK
• 获取数据
• UI 组件概览
• 应用页面（以前称为应用主页）
• 设置页面
• 应用事件（测试版）
• 应用对象（测试版）
• 配置 Webhook
• 应用市场上架要求
• 如何上架应用
• 应用认证要求
• 无服务器函数概览
• Agent 工具概览
• Agent 工具上架要求
• 使用 npm workspaces 共享代码
• 开发者 MCP 服务设置
• MCP Auth 应用（与远程 MCP 服务集成）
• 迁移到 2026.03
• 平台版本管理