generating-ui-bundle-metadata

UI Bundle 元数据

搭建新的 UI Bundle

使用 sf template generate ui-bundle 创建新应用，不要使用 create-react-app、Vite 或其他通用脚手架。

始终传入 --template reactbasic 来搭建基于 React 的 Bundle。

**UI Bundle 名称（-n）：**仅限字母数字，不得包含空格、连字符、下划线或特殊字符。

示例：

sf template generate ui-bundle -n CoffeeBoutique --template reactbasic

生成后：

1. 替换所有默认样板内容——“React App”、“Vite + React”、默认 <title>、占位文本
2. 为主页填充真实内容（着陆页板块、横幅、主视觉、导航）
3. 更新导航和占位内容（参见 building-ui-bundle-frontend 技能）
4. 配置托管目标——如果 UI Bundle 的元 XML 中没有 <target>，它就不会在组织中显示。内部应用（App Launcher）请使用 generating-ui-bundle-custom-app，外部应用（Experience Site）请使用 generating-ui-bundle-site。

在 UI Bundle 目录中运行任何脚本之前，始终先安装依赖项。

---

UIBundle Bundle

UIBundle Bundle 位于 uiBundles/<AppName>/ 下，且必须包含：

• <AppName>.uibundle-meta.xml——文件名必须与文件夹名称完全一致
• 一个构建输出目录（默认为 dist/），其中至少包含一个文件

元 XML

必填字段：masterLabel、version（最多 20 个字符）、isActive（布尔值）。 可选字段：description（最多 255 个字符）、target。

Target 字段

<target> 元素指定 UI Bundle 的托管位置：

值	用途	配套元数据
Experience	通过 Digital Experience 面向外部的网站	Network、CustomSite、DigitalExperienceConfig、DigitalExperienceBundle
CustomApplication	通过 Lightning App Launcher 使用的内部应用	CustomApplication（applications/*.app-meta.xml）

应用必须设置 <target> 才能在 Salesforce 组织中访问。部署时未指定目标的 UI Bundle 将不会出现在任何位置——既没有 App Launcher 入口，也没有 Experience Site URL。始终将 Bundle 与以下其中一项配套使用：

• generating-ui-bundle-site（用于 Experience 目标）
• generating-ui-bundle-custom-app（用于 CustomApplication 目标）

Experience 目标示例：

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>propertyrentalapp</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>Experience</target>
</UIBundle>

CustomApplication 目标示例：

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>propertymanagementapp</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

ui-bundle.json

可选文件。允许的顶层键：outputDir、routing、headers。

约束：

• 必须是有效的 UTF-8 JSON，最大 100 KB
• 根节点必须是非空对象（不得为 {}、数组或基本类型）

路径安全（适用于 outputDir 和 routing.fallback）：拒绝反斜杠、开头为 / 或 \ 的路径、.. 段、空值/控制字符、glob（*、?、**）以及 %。所有解析后的路径都必须位于 Bundle 内。

outputDir

引用子目录的非空字符串（不得为 . 或 ./）。目录必须存在且至少包含一个文件。

routing

如果存在，必须为非空对象。允许的键：rewrites、redirects、fallback、trailingSlash、fileBasedRouting。

• trailingSlash："always"、"never" 或 "auto"
• fileBasedRouting：布尔值
• fallback：符合路径安全要求的非空字符串；目标文件必须存在
• rewrites：由 { route?, rewrite } 对象组成的非空数组，例如 { "route": "/app/:path*", "rewrite": "/index.html" }
• redirects：由 { route?, redirect, statusCode? } 对象组成的非空数组；statusCode 必须为 301、302、307 或 308

headers

由 { source, headers: [{ key, value }] } 对象组成的非空数组。

示例：

{
  "routing": {
    "rewrites": [{ "route": "/app/:path*", "rewrite": "/index.html" }],
    "trailingSlash": "never"
  },
  "headers": [
    {
      "source": "/assets/**",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ]
}

**切勿建议：**将 {} 作为根节点、空的 "routing": {}、空数组、[{}]、"outputDir": "."、"outputDir": "./"。

---

CSP Trusted Sites

Salesforce 会强制执行内容安全策略标头。任何未注册为 CSP Trusted Site 的外部域名都会被阻止（图片无法加载、API 调用失败、字体缺失）。

何时创建

只要应用引用了新的外部域名，就需要创建：CDN 图片、外部字体、第三方 API、地图切片、iframe、外部样式表。

步骤

1. 识别外部域名 — 从代码中的每个外部 URL 提取源（协议 + 主机）
2. 检查现有注册项 — 查看 force-app/main/default/cspTrustedSites/
3. 将资源类型映射到 CSP 指令：

资源类型	指令字段
图片	isApplicableToImgSrc
API 调用（fetch、XHR）	isApplicableToConnectSrc
字体	isApplicableToFontSrc
样式表	isApplicableToStyleSrc
视频 / 音频	isApplicableToMediaSrc
Iframe	isApplicableToFrameSrc

对于预检 / 重定向处理，始终也将 isApplicableToConnectSrc 设为 true。

4. 创建元数据文件 — 按照 implementation/csp-metadata-format.md 中的 .cspTrustedSite-meta.xml 格式操作。将文件放在 force-app/main/default/cspTrustedSites/。