我的Salesforce CLI实战之路：文档之外的经验

二月 05, 2026

回顾我这几年在 Salesforce 开发领域的摸爬滚打，如果说有什么工具是我现在离不开的，那 Salesforce CLI (无论是之前的 sfdx 还是现在的 sf) 绝对榜上有名。它从最初一个辅助工具，逐渐演变成了我日常开发、自动化部署的核心。

刚开始接触 Salesforce 开发的时候，大部分时候还是依赖 Change Set、Workbench 或者 Ant Migration Tool。这些工具各有各的便利，但随着项目规模的增大、团队协作的加深以及对 CI/CD 流程的追求，它们的局限性也日益凸显。我记得特别清楚，有一次因为一个复杂的功能需要频繁地在不同环境间同步元数据，用 Ant Tool 写了好几个 Ant target，每次都要手动修改配置，效率低下，还容易出错。这时候，SFDX CLI 带着“源码驱动开发”的理念横空出世，一下子吸引了我的注意。

从 Ant 到 SFDX：为什么是它？

最初，我使用 SFDX CLI 只是因为它能够方便地授权 Org，执行 SOQL 查询，或者快速创建一些 Metadata。但很快，我就意识到它的真正价值在于与版本控制系统的深度整合。之前用 Ant 部署，我们总是在 Metadata API 的“包”层面进行操作，本地文件结构和 Org 里的实际结构映射关系不够直观。而 SFDX CLI 推崇的“Source Format”则完全改变了这一点。

为什么选择它？最核心的原因是：

原子化的元数据管理： SFDX CLI 将大部分元数据类型拆分成更小的文件，例如一个 Custom Object 的所有字段、List View、Validation Rule 都独立成文件。这让 Git 等版本控制系统能更好地跟踪每一次微小的变更，显著降低了合并冲突的风险。
本地开发体验的提升： 配合 VS Code 插件，SFDX CLI 让本地开发变得流畅。我可以在本地修改代码（Apex Class, LWC等），直接部署到 Org，然后通过 Source Tracking 命令看到本地和 Org 之间的差异。
Scratch Orgs： 虽然 Scratch Orgs 在某些场景下有局限性，但对于快速原型开发、特性分支开发以及 CI/CD 环境的临时 Org 创建，它简直是神器。一个干净、可重复构建的开发环境，这在 Ant 时代是难以想象的。

Scratch Orgs：理想与现实的交锋

遇到的问题：Scratch Org 的适用性

我曾一度认为 Scratch Orgs 是 Salesforce 开发的银弹，所有的开发都应该基于 Scratch Org 进行。但实践告诉我，这并非总是最佳方案。我遇到过的主要问题有：

复杂 ISV 包的集成： 如果你的项目严重依赖于一些大型的 ISV (Independent Software Vendor) 包（比如 Conga, Vlocity 等），在 Scratch Org 中部署并配置这些包通常非常耗时且复杂，有时甚至是不可能的，因为 ISV 包的许可和配置可能需要特定的 Org ID 或环境。
数据依赖与测试： 对于需要大量特定测试数据才能进行验证的功能，或者需要与外部系统进行复杂的双向集成测试时，每次重新创建 Scratch Org 并重新导入数据、重新配置集成，成本非常高。
团队协作与长期开发： 对于一个团队在同一个功能分支上进行长时间开发，或者需要共享一些公共配置的情况，频繁地创建和销毁 Scratch Orgs 反而增加了开销和沟通成本。每个人都维护自己的 Scratch Org 固然好，但有些跨团队、跨模块的功能，共享一个长期存在的开发 Sandbox 可能更实际。

我的判断与取舍：Scratch Orgs 与 Sandboxes 的平衡

最终，我并没有完全抛弃 Sandboxes。我的策略是：

Scratch Orgs 适用于： 新功能开发、Bug Fix、自动化测试、POC (Proof of Concept) 项目。即那些生命周期短、需要快速迭代、隔离性强的任务。
Sandboxes 适用于： 集成测试 (Integration Testing)、UAT (User Acceptance Testing)、性能测试、与外部系统复杂集成开发，以及那些依赖大型 ISV 包的项目。它们作为相对稳定的集成环境或准生产环境。

这种平衡的方案让我既能享受到 Scratch Orgs 的灵活性，又能处理好 Sandbox 在特定场景下的不可替代性。


# 示例：创建 Scratch Org
sf org create scratch --definition-file config/project-scratch-def.json --set-default --alias my-dev-scratch-org

# 示例：部署源到 Scratch Org
sf project deploy start --metadata-dir force-app/main/default

# 示例：拉取 Scratch Org 的变更
sf project retrieve start --metadata-dir force-app/main/default

元数据部署：`source:deploy` 的光环与阴影

踩过的坑：Profile 和 Permission Set 的部署

SFDX CLI 的 sf project deploy start (或旧的 sfdx force:source:deploy) 是我最常用的部署命令。它基于本地的 Source Format 源文件进行部署，非常方便。但它在处理 Profile 和 Permission Set 时的行为，一度让我非常头疼。

当我第一次尝试用 SFDX CLI 部署 Profile 时，我发现它往往会把 Org 中 Profile 文件的所有权限（包括不属于我项目中的对象或字段）全部清除掉，只保留我本地 Source Format 定义的权限，这在有多个开发人员、多个项目共用一个 Org 的时候，会造成严重的权限丢失问题。

后来我理解到，这是因为 Profile 文件在 Salesforce Metadata API 中的设计模式决定的。它是一个“全量”文件，部署时会覆盖目标 Org 的整个 Profile 定义，而不是增量更新。

我的解决方案和“为什么”

针对 Profile 和 Permission Set 的部署，我采取了以下几种策略：

权限集优先： 尽可能使用 Permission Set 来管理用户权限，而非直接修改 Profile。Permission Set 是增量式的，部署时只会添加或修改其中定义的权限，不会影响其他权限。这是 Salesforce 官方推荐的实践，也是最不容易出错的方式。
Profile 拆分与筛选： 如果确实需要部署 Profile（例如设置默认页布局分配、自定义应用可见性等），我们会使用一些工具或脚本（例如 SFDX CLI 的 sf project generate manifest 结合自定义脚本）来只选择性地提取和部署 Profile 文件中我们需要修改的部分，或者只部署与我们项目相关的自定义对象/字段权限。但这比较复杂，且容易出错，非必要不采纳。
退回到 Metadata API 方式： 对于极其复杂的 Profile 更新，或者需要精确控制的场景，我可能会暂时放弃 sf project deploy start，转而使用 sf project deploy start --metadata-dir /path/to/profile --api-version 59.0 --target-org my-org (或旧的 sfdx force:mdapi:deploy)。这种方式更接近 Ant Tool 的行为，但仍需小心。它通常用于部署特定的、经过严格审核的 Profile 增量变更，例如只针对某个特定 Profile 的某个权限增加。

经验告诉我，Profile 是元数据部署中最“脆弱”的环节之一，需要特别小心。最好的方法是避免直接修改它，转而使用 Permission Set。


# 示例：部署一个权限集
sf project deploy start --metadata PermissionSet:MyCustomPermissionSet

# 示例：部署一个对象及其字段
sf project deploy start --metadata CustomObject:MyCustomObject
sf project deploy start --metadata CustomField:MyCustomObject.MyCustomField__c

数据操作：`data:tree` 的便利与局限

SFDX CLI 提供了 sf data tree export 和 sf data tree import 命令，用于导出和导入带有父子关系的记录。这在某些场景下非常有用，比如创建测试数据，或者在不同 Org 间同步少量关联数据。

实际应用场景

我主要在以下场景中使用它们：

快速测试数据准备： 当我需要为一个新功能创建一整套关联的测试数据时（例如一个 Account 下的多个 Contact，每个 Contact 下有多个 Case），data:tree 可以一次性导出并导入。
演示环境数据初始化： 对于一个演示 Org，我们可能需要预置一些结构化的数据来展示功能，data:tree 是一个不错的选择。

局限性

尽管它很方便，但也有其局限性：

性能问题： 对于大量数据（例如数千条甚至数万条记录），data:tree 的性能并不理想。它通过多次 API 调用来处理父子关系和记录 ID 的映射，速度较慢。
复杂关系处理： 仅仅是简单的父子关系还好，如果涉及到多层嵌套、交叉引用或者自定义外部 ID 的场景，data:tree 会变得非常复杂，甚至无法处理。
错误处理： 当数据导入失败时，错误信息有时不够直观，定位问题比较困难。

因此，对于大量数据的导入导出或复杂的 ETL 需求，我仍然倾向于使用 Data Loader 或者专门的 ETL 工具（如 MuleSoft, Skyvia 等）。data:tree 更多是作为开发者快速创建和操作少量关联数据的“小工具”。


# 示例：导出 Account 和其关联的 Contact
sf data tree export -q "SELECT Id, Name, (SELECT Id, FirstName, LastName FROM Contacts) FROM Account WHERE Name LIKE 'Test%'" -d ./data -p

# 示例：导入数据
sf data tree import -f ./data/Account-plan.json

SFDX 到 SF：命令行的现代化

最近 Salesforce CLI 的一个重要变化是从 sfdx 切换到 sf。最初听到这个消息的时候，我感到一些困惑和不解：为什么要改变，旧的命令还能用吗？这会不会打乱我已有的自动化脚本？

后来我了解到，sf 是 Salesforce CLI 的下一代版本，旨在提供更一致、更简洁的命令结构和更好的用户体验。它整合了之前分散在不同插件中的功能，并对命名进行了优化。例如，旧的 sfdx force:source:deploy 变成了 sf project deploy start。

我的适应过程

新旧并存： 好在 Salesforce 提供了一个平滑的过渡方案，在安装 sf CLI 后，默认会安装 sfdx 的兼容性插件，这意味着我旧有的 sfdx 命令和脚本仍然可以正常运行，无需立即全部修改。这给我留下了充足的适应时间。
逐渐切换： 我在新的项目和新的脚本中，开始优先使用 sf 命令。我发现新的命令结构确实更直观，比如 sf org list 比 sfdx force:org:list 简洁明了。
理解别名： 很多命令都有别名，例如 sf deploy 实际上就是 sf project deploy start。理解这些别名可以帮助我更快地适应。

从 sfdx 到 sf 的转变，让我看到了 Salesforce 团队在工具链现代化方面的努力。尽管初期会有些适应成本，但从长远来看，这无疑是一个积极的改进。

总结与展望

Salesforce CLI，无论是 sfdx 还是 sf，都极大地改变了我的 Salesforce 开发和部署方式。它让我从繁琐的手动操作中解脱出来，能够更专注于代码和业务逻辑。它将本地开发、版本控制、自动化部署紧密结合，是构建现代化 Salesforce 开发流程不可或缺的一环。

当然，它也不是完美的。例如，在处理大型元数据量时，偶尔会遇到性能瓶颈；某些元数据类型（如复杂的流程自动化、报表文件夹结构等）在 Source Format 下的表示仍有改进空间；以及在某些元数据类型（比如 Profile）的增量更新方面，依然存在挑战。

未来，我希望 Salesforce CLI 能在以下方面继续发展：

更智能的元数据处理： 例如，更好地支持 Profile 和 Permission Set 的增量合并，或者提供更细粒度的部署选项。
更强大的数据管理能力： 在保持简洁性的前提下，提升 data:tree 等数据命令的性能和复杂关系处理能力。
与 AI 和低代码工具的深度融合： 想象一下，AI 辅助生成元数据定义，并通过 CLI 自动化部署，这会是多么令人兴奋的场景。

总体而言，我对我与 Salesforce CLI 的“旅程”非常满意。它是我效率提升的关键，也是我保持对 Salesforce 生态系统好奇心的重要动力。

Salesforce中文网