# @ds-sfdc/sfparty 中文文档

规范地址：https://npmcn.com/package/%40ds-sfdc/sfparty/

版本：3\.0\.3
npm 元数据更新时间：2026-05-18T22:07:44.724Z
中文译文更新时间：2026-11-13T01:47:03.641Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ds-sfdc/sfparty
原文对照：https://npmcn.com/package/%40ds-sfdc/sfparty/?lang=original
项目主页：https://github.com/TimPaulaskasDS/sfparty#readme
源码仓库：https://github.com/TimPaulaskasDS/sfparty

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：591 kB，111 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：17 个
- 首次发布：2023-01-07T16:05:22.510Z
- 最新版本发布：2026-05-18T22:07:44.533Z
- 近 30 天下载量：2600（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：74（近 12 个月 4 个）

## 中文简介

CI/CD 销售力元数据 XML 分解器

## 安装

```sh
npm install @ds-sfdc/sfparty
```

也可以使用：`pnpm add @ds-sfdc/sfparty`、`yarn add @ds-sfdc/sfparty`、`bun add @ds-sfdc/sfparty`

## README

# @ds-sfdc/sfparty (英语)

[![NPM](https://img.shields.io/npm/v/@ds-sfdc/sfparty.svg?label=@ds-sfdc/sfparty)](https://www.npmjs.com/package/@ds-sfdc/sfparty) [![Downloads/week](https://img.shields.io/npm/dw/@ds-sfdc/sfparty.svg)](https://npmjs.org/package/@ds-sfdc/sfparty) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://github.com/TimPaulaskasDS/sfparty/blob/main/LICENSE.md) ![CI/CD](https://github.com/TimPaulaskasDS/sfparty/actions/workflows/cicd.yaml/badge.svg)

## 为什么用sfparty?

销售力元数据一般被存储在大型的XML文件中,这需要一定的努力来配合. 这些XML文件很难读取,对diff具有挑战性,在合并时可能导致冲突并被腐蚀出XML. sfparty是一种通过将销售力元数据XML文件分拆为更小的YAML或JSON部分来改进开发者和DevOps体验的功能. 这样就更容易理解和管理元数据,消除了发生冲突和腐败的XML的风险. 此外,sfparty将这些部分重新组合到XML文件中的能力使得它成为CI/CD需求的理想解决方案. 它可以方便地进行版本控制和精简部署程序.

## 安装

```bash
npm i -g @ds-sfdc/sfparty
```

### 国家预防机制安装问题

`command not found: sfparty`  
sfparti是一个可执行文件,意在全球安装.

`EACCESS: permission denied` 关于如何解决国家预防机制的EACCESS问题,有若干备选方案。 使用最简单的方式 `sudo`

```bash
sudo npm i -g @ds-sfdc/sfparty
```

取决于你的系统,你可能会有一些问题 安装sfpart 使用国家预防机制。 这些通常是文件系统权限问题. 这里与各种条款有一些联系,就如何解决这一问题提出了建议.

[修复 npm 权限问题](https://kaustubhtalathi.medium.com/fixing-npm-permission-issue-f3d88a7a4ab4)  
[总是使用 sudo 安装全局软件包](https://stackoverflow.com/questions/16151018/how-to-fix-npm-throwing-error-without-sudo#:~:text=always%20use%20sudo%20%2Di%20or,they%20are%20owned%20by%20root)  
[使用 npm 配置而不是使用 chown 或 chmod](https://stackoverflow.com/questions/16151018/how-to-fix-npm-throwing-error-without-sudo/41395398#41395398)

## 图标

### 分开

```bash
sfparty split
```

### 组合

```bash
sfparty combine
```

### 更新

```bash
sfparty update
```

### 选项

```
-y, --type     type(s) of metadata to process
-n, --name     name of metadata file  
-f, --format   format to use yaml (default) or json
-s, --source   package directory path specified in sfdx-project.json  
-t, --target   target path to directory to create yaml/json files  
-g, --git      combine files based on git commits
-h, --help     Show help  
-v, --version  Show version
```

### 组合选项

使用组合命令时有下列选项:

#### gi

```
-g, --git      process files based on git commits. This option does not require a value.
```

##### Git 选项

使用组合命令时有下列选项:

```
-a, --append      append package and destructive package instead of overwriting.
-l, --delta       when possible create delta metadata files for CI/CD deployment.
-p, --package     path to your change package XML file.
-x, --destructive path to your destructive change package XML file.
```

## 实例

### 自定义标签

```bash
sfparty split --type=label
```

### 权限设置

```bash
sfparty split --type=permset
sfparty split --type=permset --name="My Permission Set"
```

### 简介

```bash
sfparty split --type=profile
sfparty split --type=profile --name="My Profile"
```

### 工作流程

```bash
sfparty split --type=workflow
sfparty split --type=workflow --name="Workflow"
```

### 多种类型

```bash
sfparty split --type="workflow,label"
```

### 源目录

源目录将使用 sfdx- project.json 文件所指定的您的默认包文件夹, 因此必须从您的 Salesforce 项目目录中执行 。 如果主/ 默认文件夹不存在, 它将创建它们 .

```
{
    "packageDirectories": [
        {
            "path": "force-app",
            "default": true
        },
        {
            "path": "my-package"
        }
    ],
    "namespace": "",
    "sfdcLoginUrl": "https://login.salesforce.com",
    "sourceApiVersion": "56.0"
}
```

```bash
sfparty split --source="my-package"
```

### 目标目录

源目录将使用 sfdx- project.json 文件中规定的您的默认包文件夹, 以及附件 `-party` 最终。 例如,如果默认源路径是 `force-app`,则默认目标目录将是 `force-app-party` 除非另有说明。 目标不需要在 sfdx- project.json 中指定,但是合并命令不会在 sfdx-project.json 中没有指定的文件夹上工作.

```bash
sfparty split --target="test"
```

## 胡斯基·吉特·胡克斯

如果您使用 Git 钩工具, 如 `husky`,可以添加后置钩来自动运行 `combine` 当执行时命令 `merge` 或者说 `git pull` 命令.

### 发生后

```
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

sfparty combine --git
```

## 排雷中心/发改委

sfparti是用于补充您的 CI/CD 进程。 你的管道应该已经建成了 `package.xml` 财务报告和审定财务报表 `destructiveChanges.xml`当sfparty运行时,它会做一个 `git diff` 并附加文件的更改。 你可以使用一个工具,比如 [sfdx- git- 德尔塔](https://www.npmjs.com/package/sfdx-git-delta) 以建立 包.

```
Command:
sfparty combine --git

Required:  
-g, --git         process files based on git commits. This option does not require a value.

Optional:  
-a, --append      append package and destructive package instead of overwriting.
-l, --delta       when possible create delta metadata files for CI/CD deployment.
-p, --package     path to your change package XML file.
-x, --destructive path to your destructive change package XML file.
```

### 示例

#### 上一个提交当前

```
sfparty combine --git=HEAD~1..HEAD --append --delta --package=deploy/package.xml --destructive=deploy/destructiveChanges/destructiveChanges.xml
```

#### 上一个承诺当前并输出到不同的目标目录

默认目标是在 `sfdx-project.json` 文档。 你可以用这个 `--target` 如果您想要在另一个位置创建文件,则参数。 sfparty将相应创建/main/default/\*目录.

```
sfparty combine --git=HEAD~1..HEAD --append --delta --package=deploy/package.xml --destructive=deploy/destructiveChanges/destructiveChanges.xml --target=deployDir/force-app
```

## 常见问题

### @ds-sfdc/sfparty 是什么？

CI/CD 销售力元数据 XML 分解器

### 如何安装 @ds-sfdc/sfparty？

在项目目录运行 npm install @ds-sfdc/sfparty，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sfparty，可以用 npx sfparty 直接运行。

### @ds-sfdc/sfparty 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ds-sfdc/sfparty 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ds-sfdc/sfparty 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ds-sfdc/sfparty 可以商用吗？

@ds-sfdc/sfparty 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @ds-sfdc/sfparty 的下载量有多少？

根据 npm 官方下载统计，@ds-sfdc/sfparty 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,600 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ds-sfdc/sfparty 还在维护吗？

最新版本 3\.0\.3 发布于 2026/05/19（5 个月前）；至今共发布 74 个版本，其中过去 12 个月发布了 4 个；首次发布于 2023/01/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。