sf-multiframework

Salesforce 多框架

构建由 Salesforce 托管为 UIBundle 元数据的独立前端应用。 React 和 Angular 提供了文档化模板；保留用户使用的框架和创作工具。 对于可复用的平台组件，LWC 仍是原生选择。

本技能于 2026 年 10 月 8 日审阅。有关最新的主要链接、 研究发现和特定范围的发布状态，请使用 official-sources.md。详情有所差异时，请检查目标 org、 已安装 CLI 的帮助信息、锁定文件和包声明。 将历史演示修复和示例约定视为本地指导。

选择相关参考资料

只阅读任务所需的内容；可选的应用模式并非前置条件。

任务	阅读
首个应用、org 资格、域名设置	overview.md、setup.md、activation-checklist.md
创建脚手架或修复元数据	templates.md、project-structure.md、cli-guide.md
Angular 实现	angular.md
记录查询、变更、REST、架构/codegen	data-sdk.md、graphql-workflow.md、error-handling.md
自定义标签、SDK 扩展、本地化格式、应用标识、宿主 UI	platform-capabilities.md
Agentforce Employee Agent 聊天	acc-integration.md
在 Lightning 或 Experience 页面中嵌入应用	microfrontends.md
外部站点、访客和已认证用户	templates.md、experience-cloud-runbook.md、permissions-csp.md
测试、部署、App Manager、访问权限	testing.md、ci-deploy.md、permissions-csp.md
托管/非托管 2GP 分发	packaging.md
现有 Beta 应用	beta-to-ga-migration.md
框架选择、故障诊断	lwc-vs-react.md、troubleshooting.md
样式或 React 导航	styling.md、react-router.md
创作工具设置	authoring-surface.md
教学示例	recipe-conventions.md
请求工作区外壳或自定义大模型界面	layout-patterns.md、llm-ui-patterns.md
请求评分审计	scoring-rubric.md — 本地评分标准，并非 Salesforce 认证

关键决策

在询问之前，先从工作区判断框架、受众、org 别名、现有项目结构和所需功能。 区分内部 CustomApplication 应用与外部 Experience 应用容器，并将两者与 iframe 嵌入区分开来。 创建新应用并不意味着获准更改 org 级设置或发布应用。

符合资格的版本为 Hyperforce 上的 Enterprise、Performance、Unlimited、Developer 或 Partner Developer 版本，不包括 Alibaba Cloud 和 Government Cloud。 内部托管需要 Salesforce 应用域名和 Salesforce Edge Network。 不要仅凭“sandbox”或“production”标签判断是否符合资格。

平台不变量

• 在 bundle 目录中运行 npm 命令，而不是在 DX 项目根目录中。遵循生成的框架脚本，并保留 Salesforce 构建/代理集成。
• bundle 的 XML 使用 isActive 和整数类型的架构 version（通常为 1）。内部应用需要配套的 CustomApplication，并使用限定名 uiBundle 引用，例如 c__myApp；外部应用需要全部四种站点元数据类型。
• ui-bundle.json.outputDir 必须包含构建后的资源。对于 SPA，使用 routing.fallback: "index.html"。其可选的 apiVersion 是有文档说明的 vXX.X 字符串，与 DX 的 sourceApiVersion: "XX.X" 不同。
• 使用 @salesforce/platform-sdk/data 发起 Salesforce 请求；读取时优先使用 sdk.graphql?.query({ query, variables })，写入时优先使用 sdk.graphql?.mutate({ mutation, variables })。对于受支持的 REST API，使用 sdk.fetch?.()。绝不能用原生 fetch/axios 替代 Salesforce 请求。
• 对缺失的 SDK 功能和缺失的 result.data 做防护。区分不可用的界面或失败的请求与成功但没有返回行的查询。使用组织架构/生成的类型；Name { value } 这样的字段封装与 Id 这样的标量并存。
• 查询提供 subscribe() 和 refresh()；请清理订阅。这些是缓存/刷新通知，并非服务器推送订阅。变更不会更新查询缓存；写入后刷新相关查询。
• 缓存存储按基础 URL 和 API 版本分区；查询键也包含标头。冷缓存中的 only-if-cached 请求会解析为 errors[].extensions.code === "CACHE_MISS"，而不会抛出异常。
• HTTP 回调应放在 webapp.onStatus 下，并以状态码为键。允许正常的界面检测；不要自行设置小写的 "webapp" 覆盖项。
• 应用可见性、API Enabled、对象/字段访问权限和记录共享是彼此独立的授权。部署访问权限集并不会为用户分配该权限集。UI API 安全机制不会自动保护自定义 Apex REST 逻辑。
• 在应用内使用标准 npm/框架 API。LWC 虚拟导入（例如 @salesforce/apex/*、@salesforce/schema/*、lightning/* 和 @wire）不可用。受支持的平台 SDK /view、/i18n 和 /data/extensions 入口点有效；不要禁止所有 @salesforce/* 包。
• ACC 已验证的包导出项是 embedAgentforceClient，其中嵌套了 agentforceClientConfig。复制旧版 createAccWidget 示例前，请先核实声明。External Service Agent 聊天使用 Enhanced Chat v2。
• 部署元数据前先构建；包含配套元数据，并以预期用户的身份检查已部署的应用。bundle 上限为最多 2,500 个文件。如果托管 AppExchange 审核要求保留 sourcemap，请勿删除。

典型开发流程

对于全新的完整应用，使用 sf template generate project 时，选择 reactinternalapp、reactexternalapp、angularinternalapp 或 angularexternalapp。 对于现有 DX 项目中的 bundle，使用 sf template generate ui-bundle 时，选择 reactbasic 或 angularbasic；并单独提供配套元数据。 请查看已安装命令的帮助，而不要将完整项目模板视为旧版 bundle 模板。

在 bundle 中安装依赖。必要时，获取已授权组织的 GraphQL 架构；使用项目脚本生成操作类型，然后运行框架的开发服务器。本地开发和 Live Preview 无法证明已部署的权限、会话、CSP 或深层路由可正常运行。

运行现有的 lint/build 和相关测试。在用户要求的范围内，通过用户的 CLI 或可用的 Salesforce DX MCP 工具进行部署。使用实际公开的 MCP 架构，而不是硬编码工具标识符。通过 App Launcher 或 Experience site 启动，分配已授权的访问权限，并验证记录、写入结果和路由刷新。记录哪些检查是在本地进行的，哪些使用了已部署的组织。

assets/README.md 提供可调整的元数据和 React 示例；完整的 React 或 Angular 项目请使用官方模板。可选的布局、聊天和评分资源并不授权开展额外工作。