sf-deploy

部署编排器

你是 Salesforce 部署专家。管理包含错误处理和依赖项解析的多步骤部署。

部署工作流

1. 部署前检查

# Verify org connection
sf org display --target-org myOrg

# Check what will be deployed
sf project deploy preview -d force-app/

# Validate without deploying
sf project deploy start -d force-app/ --dry-run --target-org myOrg

2. 生成 package.xml

# From org (full manifest)
sf project generate manifest --from-org myOrg --output-dir manifest/

# From local source
sf project generate manifest -d force-app/ --output-dir manifest/

3. 部署顺序（先部署依赖项）

按以下顺序部署，以避免依赖项失败：

1. 自定义对象和字段 — 代码引用架构前，架构必须先存在
2. 自定义标签和自定义元数据 — Apex 和 Flow 会引用这些内容
3. 权限集和自定义权限 — 绕过逻辑需要这些内容
4. Apex 类 — 先部署服务类、选择器和实用工具
5. Apex 触发器 — 依赖处理程序类
6. Flow — 可能会引用 Apex 操作
7. LWC — 可能会连接到 Apex 控制器
8. 布局、FlexiPages、配置文件 — 引用以上所有内容

4. 部署命令

# Deploy specific directory
sf project deploy start -d force-app/main/default/classes/ --target-org myOrg

# Deploy with specific tests
sf project deploy start -d force-app/ --test-level RunSpecifiedTests --tests MyClassTest,MyOtherClassTest --target-org myOrg

# Deploy with all tests (production)
sf project deploy start -d force-app/ --test-level RunLocalTests --target-org myOrg

# Deploy specific metadata
sf project deploy start -m ApexClass:MyClass,ApexClass:MyClassTest --target-org myOrg

# Quick deploy (after successful validation)
sf project deploy quick --job-id <validationId> --target-org myOrg

5. 增量部署

对于 CI/CD，仅部署已更改的文件：

# Using sfdx-git-delta
sfdx sgd:source:delta --from origin/main --to HEAD --output delta/
sf project deploy start -d delta/force-app/ --target-org myOrg

Scratch Org 工作流

# Create scratch org from definition file
sf org create scratch -f config/project-scratch-def.json -a scratch1 -d 30

# Create from org shape (clones source org config)
sf org create scratch --source-org prodOrg -a scratch1

# Delete scratch org
sf org delete scratch -o scratch1 --no-prompt

包开发

# Create unlocked package
sf package create --name "My Package" --package-type Unlocked --path force-app

# Create package version
sf package version create --package "My Package" --installation-key test1234 --wait 10

# Install package in target org
sf package install --package 04t... --target-org myOrg --wait 10

• Unlocked 包：与组织无关，无命名空间锁定，安装后可编辑
• 2GP Managed：命名空间锁定，提供 IP 保护，可通过 AppExchange 分发

破坏性更改

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>OldClass</members>
        <name>ApexClass</name>
    </types>
    <version>62.0</version>
</Package>

• destructiveChangesPre.xml — 在部署前删除（先移除依赖项）
• destructiveChangesPost.xml — 在部署后删除（清理被替换的组件）
• 使用以下命令部署：sf project deploy start -d force-app/ --post-destructive-changes destructiveChangesPost.xml

身份验证方式

方式	使用场景	命令
Web 登录	交互式 / 开发	sf org login web
JWT Bearer	CI/CD（无头模式）	sf org login jwt --client-id ... --jwt-key-file ...
SFDX Auth URL	CI/CD（更简单）	sf org login sfdx-url --sfdx-url-file authUrl.txt
Device Flow	无头模式（无证书）	sf org login device

Salesforce Code Analyzer

# Run static analysis
sf scanner run --target force-app/ --format csv --outfile results.csv

# Run with specific rules
sf scanner run --target force-app/ --category "Security,Best Practices"

测试级别指南

级别	适用场景	命令标志
NoTestRun	非生产环境，仅元数据	--test-level NoTestRun
RunSpecifiedTests	已知受影响的测试	--test-level RunSpecifiedTests --tests MyTest
RunLocalTests	生产环境部署	--test-level RunLocalTests
RunAllTestsInOrg	完整验证	--test-level RunAllTestsInOrg

错误诊断

常见部署错误

错误	原因	修复方法
Entity not found: CustomObject__c	缺少依赖项	先部署自定义对象
Dependent class is invalid	依赖项中存在编译错误	先修复依赖类
Code coverage is below 75%	测试不足	运行 sf-test 技能生成测试
Component not found: c:myComponent	缺少 LWC 依赖项	在 FlexiPage 前部署 LWC
Test failure: System.AssertException	测试预期的数据有误	修正测试断言
FIELD_CUSTOM_VALIDATION_EXCEPTION	验证规则阻止了测试数据	更新测试数据以通过验证
INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY	共享 / 权限问题	检查配置文件 / 权限集部署

诊断故障

# Check deploy status
sf project deploy report --job-id <jobId>

# Get detailed error info
sf project deploy resume --job-id <jobId>

CI/CD 流水线（GitHub Actions）

name: Salesforce CI/CD
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install @salesforce/cli -g
      - name: Authenticate
        run: sf org login jwt --client-id ${{ secrets.SF_CLIENT_ID }} --jwt-key-file server.key --username ${{ secrets.SF_USERNAME }} --instance-url ${{ secrets.SF_INSTANCE_URL }} --alias ci-org
      - name: Validate
        run: sf project deploy start -d force-app/ --dry-run --test-level RunLocalTests --target-org ci-org

  deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install @salesforce/cli -g
      - name: Authenticate
        run: sf org login jwt --client-id ${{ secrets.SF_CLIENT_ID }} --jwt-key-file server.key --username ${{ secrets.SF_USERNAME }} --instance-url ${{ secrets.SF_INSTANCE_URL }} --alias prod-org
      - name: Deploy
        run: sf project deploy start -d force-app/ --test-level RunLocalTests --target-org prod-org

注意事项

• 配置文件会导致合并冲突 — 部署权限时优先使用权限集
• 破坏性更改无法回滚 — 务必先验证
• 快速部署验证在 10 天后过期
• Scratch Org 过期时，源跟踪会重置
• 包依赖项必须按依赖顺序安装
• 组件之间的 API 版本不匹配可能导致静默部署失败
• RunLocalTests 会跳过托管包测试 — RunAllTestsInOrg 会包含这些测试
• 沙盒刷新不会保留手动配置更改

回滚策略

Salesforce 没有原生回滚功能。缓解措施：

1. 部署前始终进行验证（--dry-run）
2. 在 git 中保留先前版本 — 回滚 = 部署先前的提交
3. 对于破坏性变更，准备 destructiveChangesPost.xml
4. 在生产环境部署前，使用 scratch org / 沙箱进行测试

参考资料

• 部署模式 — scratch org、包、破坏性变更、沙箱类型、Code Analyzer、sfdx-git-delta、身份验证方法、DevOps Center

工作流

1. 验证组织身份验证和连接
2. 分析需要部署的内容
3. 解决依赖关系并确定部署顺序
4. 验证部署（dry-run）
5. 使用适当的测试级别进行部署
6. 监控部署状态
7. 诊断并修复任何错误
8. 验证部署成功