experience-ui-bundle-site-generate

React UI Bundle 数字体验站点

创建并配置 Salesforce 上托管 React UI Bundle 的数字体验站点。此技能会生成所需的最少站点基础设施——Network、CustomSite、DigitalExperienceConfig、DigitalExperienceBundle，以及 sfdc_cms__site 内容类型——以便 React 应用可以通过 Salesforce 提供服务。

React 站点与标准 LWR 站点不同：它们不需要路由、视图、主题布局或品牌集。站点充当轻量容器（appContainer: true），将渲染工作交给 appSpace 引用的 React UI Bundle。

必需属性

生成任何元数据之前，先解析全部五项属性。每项都有回退链——按顺序尝试每个选项，直到找到值。

属性	格式	解析方式
siteName	UpperCamelCase（例如，MyCommunity）	询问用户或根据上下文推导
siteUrlPathPrefix	All lowercase（例如，mycommunity）	用户提供，或将 siteName 转为仅包含字母数字字符的全小写形式
appNamespace	字符串	sfdx-project.json 中的 namespace → sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias} → 默认为 c
appDevName	字符串	项目中的 UIBundle 元数据 → sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias} → 默认为 siteName
enableGuestAccess	布尔值	询问用户是否允许未经过身份验证的访客用户访问站点 API → 默认为 false

appNamespace 和 appDevName 属性记录预期的 UIBundle 绑定，以便后续更新；在初始创建站点时，它们不会被替换到 appSpace 中。初始创建时，sfdc_cms__site 的 content.json 中的 appSpace 始终为 ""——原因和后续流程请参阅 configure-metadata-digital-experience.md。

语言属性

此技能始终会在 sfdc_cms__site 旁生成 sfdc_cms__languageSettings。为每个站点解析 defaultLocale（默认为 en_US）；只有用户要求添加默认语言之外的其他语言时，才解析 languages。

属性	格式	解析方式
defaultLocale	xx 或 xx_YY（例如，en、en_US）	询问用户 → 默认为 en_US
languages	{label, locale} 列表	仅当用户要求多种语言、多个地区设置、国际化或翻译支持时：询问站点支持哪些其他语言。未提出此类要求时，languageSettings 内容仅声明已解析的 defaultLocale，作为单语言条目。

内容项文件夹名称（languages）、title（LanguageContent）和 urlName（languagecontent）是固定的 Experience Builder 自动默认值——并非由用户编写。请参阅 configure-metadata-language-settings.md。

预检：目标组织版本（仅限多语言）

sfdc_cms__languageSettings 内容类型仅在 Salesforce Release 264（API v68.0 或更高版本）上接受多语言声明。仅采用单一地区设置 en_US 声明的站点可在任何组织上运行，无需进行此检查。

当用户要求多种语言时，必须在写入任何元数据之前验证目标组织支持的最高 API 版本。sf api request rest 会直接在实例上访问 /services/data/，并在传输层处理身份验证，因此返回的是该组织的实际版本上限，且不会有任何访问令牌进入此脚本的上下文。

MAX_API=$(sf api request rest "/services/data/" --target-org "${usernameOrAlias}" \
          | jq -r '[.[].version | tonumber] | max')

awk -v v="$MAX_API" 'BEGIN{ exit !(v+0 >= 68.0) }' \
  || { echo "ERROR: multi-language site containers require Salesforce Release 264 (API v68.0+). Target org's maximum supported API version is v${MAX_API}. Retarget to a Release 264+ org, or reduce the site to a single-locale (en_US) declaration." >&2; exit 1; }

如果检查失败，则不要写入元数据。向用户说明版本不匹配并停止。

生成工作流

步骤 1：解析所有必需属性

在构建任何内容之前，先确定全部五个必需属性和语言属性 defaultLocale 的值。使用上方表格中的解析策略，按顺序尝试各个选项，直到找到一个值。只有在用户要求支持多种语言时，才解析 languages 属性；如果用户有此要求，请先运行上方的 预检，再继续步骤 2。

步骤 2：创建项目结构

使用可用的 Salesforce 元数据架构和字段上下文来处理 Network、CustomSite、DigitalExperienceConfig 和 DigitalExperienceBundle，确保每个文件都采用有效结构。

使用以下路径创建所有尚不存在的文件和目录：

元数据类型	路径
Network	networks/{siteName}.network-meta.xml
CustomSite	sites/{siteName}.site-meta.xml
DigitalExperienceConfig	digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml
DigitalExperienceBundle	digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml
DigitalExperience (sfdc_cms__site)	digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*
DigitalExperience (sfdc_cms__languageSettings)	digitalExperiences/site/{siteName}1/sfdc_cms__languageSettings/languages/*

每个 DigitalExperience 内容类型目录中只能包含 _meta.json 和 content.json。sfdc_cms__site 和 sfdc_cms__languageSettings 始终是 bundle 中必需的内容。sfdc_cms__languageSettings 默认仅声明已解析的 defaultLocale（例如 en_US）；用户要求支持多种语言时，再添加其他语言。不允许使用其他内容类型。

步骤 3：填充所有元数据字段

使用下方文档中的默认模板。{大括号} 中的值是已解析的属性引用，请将其替换为步骤 1 中的实际值。

元数据类型	模板参考
Network	configure-metadata-network.md
CustomSite	configure-metadata-custom-site.md
DigitalExperienceConfig	configure-metadata-digital-experience-config.md
DigitalExperienceBundle	configure-metadata-digital-experience-bundle.md
DigitalExperience (sfdc_cms__site)	configure-metadata-digital-experience.md
DigitalExperience (sfdc_cms__languageSettings)	configure-metadata-language-settings.md

有关 URL 更新，请参阅 update-site-urls.md。

步骤 3 的执行说明：加载并使用文档

• Agent 在尝试填充元数据字段之前，必须阅读步骤 3 中引用的每个 references/*.md 文件的全部内容。
• 使用平台提供的文件读取工具（例如 read_file）完整加载这些文件，然后根据步骤 1 中解析出的属性，替换 {大括号} 中的占位符。
• 需要加载的文件：
  • references/configure-metadata-network.md
  • references/configure-metadata-custom-site.md
  • references/configure-metadata-digital-experience-config.md
  • references/configure-metadata-digital-experience-bundle.md
  • references/configure-metadata-digital-experience.md
  • references/configure-metadata-language-settings.md
• 阅读文件的全部内容，替换占位符（例如 {siteName}）为解析出的值，然后使用展开后的模板填充元数据 XML/JSON 内容。

步骤 4：不要修改非模板化属性

不要修改 Network、CustomSite、DigitalExperience、DigitalExperienceConfig 或 DigitalExperienceBundle 元数据中未以 {大括号} 包裹的变量形式表示的任何默认属性值。

验证清单

部署前，请确认：

• 所有五个必需属性均已解析，且 defaultLocale 已解析（如果用户未指定，则默认为 en_US）
• 所有元数据目录和文件均按项目结构存在
• 所有元数据字段均与步骤 3 模板匹配，且仅替换了 {大括号} 中的内容；没有添加或更改其他默认属性值
• sfdc_cms__site content.json 中的 appSpace 是空字符串 ""（初始站点创建时绝不绑定 appSpace；这是 UIBundle 部署到目标组织后的单独后续更新）
• sfdc_cms__languageSettings/languages/ 文件均存在。语言声明满足以下所有平台规则：
  • defaultLocale 与某个已声明且处于启用状态的语言的 locale 相匹配
  • 每个 locale 均受 Salesforce 支持，每种语言的 isActive: true，每组 locale + label 组合均唯一，且声明的语言数量不超过平台上限
  • 完整规则目录请参阅 configure-metadata-language-settings.md。单语言默认声明天然满足所有规则。
• 部署验证成功（DigitalExperience 类型已包含 sfdc_cms__languageSettings，无需更改 --metadata 列表）：

sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}

常见工作流

更新 Experience 站点 URL

适用场景：用户希望更新或更改站点 URL（urlPathPrefix）。

步骤：

• 阅读 update-site-urls.md，了解三组件架构和 URL 更新工作流
• 按照文档中的逐步工作流，在全部三个组件（DigitalExperienceConfig、Network、CustomSite）中一致地更新 URL

配置多语言支持

适用场景：用户希望站点支持多种语言、区域设置、国际化或翻译；这超出了每个站点已有的仅声明默认区域设置的范围。

步骤：

• 收集站点应支持的其他语言，以及哪个区域设置为默认值（解析上文中的 defaultLocale 和 languages 属性）
• 运行 预检：目标组织版本 检查——如果组织版本低于 Release 264（API v68+），则中止
• 阅读 configure-metadata-language-settings.md，了解模板、字段参考和平台验证规则
• 扩展 sfdc_cms__languageSettings/languages/content.json（该文件已包含默认区域设置），添加其他语言条目，然后重新运行部署验证

注意： 这仅涉及创作——已声明的区域设置可以顺利部署，但请求时区域设置路径路由尚不能解析。不要翻译 UI 包内容；此处仅声明站点支持的语言。