# @financial-times/package-json 中文文档

规范地址：https://npmcn.com/package/%40financial-times/package-json/

版本：4\.1\.0
npm 元数据更新时间：2026-11-09T13:05:12.987Z
中文译文更新时间：2026-11-14T20:13:47.333Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40financial-times/package-json
原文对照：https://npmcn.com/package/%40financial-times/package-json/?lang=original
项目主页：https://github.com/Financial-Times/tooling-helpers/blob/HEAD/packages/package-json/README.md
源码仓库：https://github.com/financial-times/tooling-helpers

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

- 包体积（解压后）：69.3 kB，18 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：16\.x \|\| 18\.x \|\| 20\.x \|\| 22\.x \|\| 24\.x \|\| 26\.x
- 运行依赖：0 个
- 首次发布：2019-02-20T12:58:39.049Z
- 最新版本发布：2026-11-09T13:05:12.777Z
- 近 30 天下载量：2232（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 1 个）

## 中文简介

此库允许您加载、 操纵和写入内容 [`package.json`](https://docs.npmjs.com/files/package.json.html) 文档。 它还规定: [更改日志](https://npmcn.com/package/%40financial-times/package-json/#description-getchangelog) 详细说明已作出的修改.

## 安装

```sh
npm install @financial-times/package-json
```

也可以使用：`pnpm add @financial-times/package-json`、`yarn add @financial-times/package-json`、`bun add @financial-times/package-json`

## README

# 软件包-json

此库允许您加载、操纵和写入内容 (单位:千美元) [`package.json`](https://docs.npmjs.com/files/package.json.html) 文档. 它还规定: [更改日志](https://npmcn.com/package/%40financial-times/package-json/#readme-getchangelog) 详细说明任何更改 这已经做了.

# 使用量

```
npm install @financial-times/package-json
```

## 装入包 Json

装入指定后 `package.json` 文档输入内存 `loadPackageJson` 方法返回可用于修改 `package.json` 文档并把这些修改写回磁盘中.

```javascript
const loadPackageJson = require("@financial-times/package-json");
const packageJson = loadPackageJson({ filepath: `filepath/to/package.json` });
```

返回的方法 :

-   [起来](https://npmcn.com/package/%40financial-times/package-json/#readme-get)
-   [有变化可写入](https://npmcn.com/package/%40financial-times/package-json/#readme-haschangestowrite)
-   [写入更改](https://npmcn.com/package/%40financial-times/package-json/#readme-writechanges)
-   [获取字段](https://npmcn.com/package/%40financial-times/package-json/#readme-getfield)
-   [设置](https://npmcn.com/package/%40financial-times/package-json/#readme-setfield)
-   [删除字段](https://npmcn.com/package/%40financial-times/package-json/#readme-removefield)
-   [需要依赖性](https://npmcn.com/package/%40financial-times/package-json/#readme-requiredependency)
-   [删除依赖性](https://npmcn.com/package/%40financial-times/package-json/#readme-removedependency)
-   [需要脚本](https://npmcn.com/package/%40financial-times/package-json/#readme-requirescript)
-   [删除脚本](https://npmcn.com/package/%40financial-times/package-json/#readme-removescript)
-   [获取 Changgerog](https://npmcn.com/package/%40financial-times/package-json/#readme-getchangelog)

### 起来

返回代表当前工作状态的对象 `package.json` 文档。 如果尚未通过调用来写入更改, 这可能与文件系统中存在的内容不同 `writeChanges` 方法.

```javascript
packageJson.get();
```

### 有变化可写入

检查是否有要写入的文件更改 .

```javascript
packageJson.hasChangesToWrite(); // true or false
```

### 写入更改

写给 `package.json` 文档.

```javascript
packageJson.writeChanges(); // true
```

### 获取字段

从中获取特定字段 `package.json` 对象,通过传递字段作为参数.

```javascript
packageJson.getField("name"); // "@financial-times/package-json"
```

### 设置

设置特定字段的值 `package.json` 对象并返回更改日志条目.

```javascript
packageJson.setField("name", "newName");
```

返回更改日志条目对象 :

```json
{
  "event": "setField",
  "field": "name",
  "meta": {},
  "previousValue": "oldName",
  "alreadyExisted": false
}
```

### 删除字段

删除 `package.json` 对象并返回更改日志条目.

```javascript
packageJson.removeField("license");
```

返回更改日志条目对象 :

```json
{
  "event": "removeField",
  "field": "license",
  "meta": {},
  "previousValue": "MIT",
  "alreadyExisted": true
}
```

### 需要依赖性

要求软件包作为依赖存在于 `package.json`。 。 。 .

```javascript
packageJson.requireDependency({
  pkg: "prettier",
  version: "1.16.4",
  field: "devDependencies"
});
```

返回更改日志条目对象 :

```json
{
  "event": "requireDependency",
  "field": "devDependencies",
  "meta": {
    "pkg": "prettier",
    "version": "1.16.4"
  },
  "previousValue": "1.16.3",
  "alreadyExisted": true
}
```

### 删除依赖性

删除作为依赖的软件包 `package.json`。 。 。 .

```javascript
packageJson.removeDependency({
  pkg: "prettier",
  version: "1.16.4",
  field: "devDependencies"
});
```

返回更改日志条目对象,或 `false` 如果依赖不存在:

```json
{
  "event": "removeDependency",
  "field": "devDependencies",
  "meta": {
    "pkg": "prettier"
  },
  "previousValue": "1.16.3",
  "alreadyExisted": true
}
```

### 需要脚本

要求脚本存在于 `scripts` 领域 `package.json`。 。 。 .

```javascript
packageJson.requireScript({
  stage: "test",
  command: "npm run unit-test"
});
```

返回更改日志条目对象 :

```json
{
  "event": "requireScript",
  "field": "scripts",
  "meta": {
    "stage": "test"
  },
  "alreadyExisted": true
}
```

### 删除脚本

要求脚本存在于 `scripts` 领域 `package.json`。 。 。 .

```javascript
packageJson.removeScript({
  stage: "lint"
});
```

返回更改日志条目对象 :

```json
{
  "event": "removeScript",
  "field": "scripts",
  "meta": {
    "stage": "lint"
  },
  "alreadyExisted": true
}
```

### 获取 Changgerog

更改日志代表了对 `package.json` 对象,无论是否已经写入文件.

更改日志由条目对象组成,这些对象都具有以下属性:

-   `event` - 活动的类型,即. `setField`, (中文(简体) ), `requireDependency`, (中文(简体) ), `removeDependency` 或者说 `requireScript`
-   `field` - 球场在 `package.json` 已经改变
-   `alreadyExisted` - 标记字段是否已经存在
-   `previousValue` - 该字段的上个值
-   `meta` - 包含变化等额外细节的物体. `pkg`, (中文(简体) ), `version`, (中文(简体) ), `stage`

您可以使用下列方法访问更改日志条目:

-   `getChangelog()`
-   `getChangelog.asMessages()`
-   `getChangelog.lastEntry()`
-   `getChangelog.lastEntryAsMessage()`

**与更改日志合作的例子**

```javascript
packageJson.requireDependency({
  pkg: "prettier",
  version: "1.16.4",
  field: "devDependencies"
});

packageJson.requireScript({
  stage: "test",
  command: "npm run unit-test"
});

const changelogObjects = packageJson.getChangelog();

/*
[
  {
    event: "requireDependency",
    field: "devDependencies",
    meta: {
      pkg: "prettier",
      version: "1.16.4"
    },
    previousValue: "1.16.3",
    alreadyExisted: true
  },
  {
    event: "requireScript",
    field: "scripts",
    meta: {
      stage: "test"
    },
    alreadyExisted: true
  }
]
*/

const changelogMessages = packageJson.getChangelog.asMessages();

/*
[
  "Required package prettier@1.16.4 in devDependencies, previously 1.16.3",
  "Required script for stage 'test' (overwrote existing command)"
]
*/

const lastChangelogEntryObject = packageJson.getChangelog.lastEntry();

/*
{
  event: "requireScript",
  field: "scripts",
  meta: {
    stage: "test"
  },
  alreadyExisted: true
}
*/

const lastChangelogEntryMessage = packageJson.getChangelog.lastEntryAsMessage();

// "Required script for stage 'test' (overwrote existing command)"
```

## 常见问题

### @financial-times/package-json 是什么？

此库允许您加载、 操纵和写入内容 package\.json 文档。 它还规定: 更改日志 详细说明已作出的修改\.

### 如何安装 @financial-times/package-json？

在项目目录运行 npm install @financial-times/package-json，或使用 pnpm add / yarn add / bun add。

### @financial-times/package-json 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/financial-times\_\_package-json 是否存在。

### @financial-times/package-json 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @financial-times/package-json 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js 16\.x \|\| 18\.x \|\| 20\.x \|\| 22\.x \|\| 24\.x \|\| 26\.x。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @financial-times/package-json 可以商用吗？

@financial-times/package-json 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @financial-times/package-json 的下载量有多少？

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

### @financial-times/package-json 还在维护吗？

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