# cz-cubics 中文文档

规范地址：https://npmcn.com/package/cz-cubics/

版本：0\.0\.12
npm 元数据更新时间：2026-11-03T09:03:20.069Z
中文译文更新时间：2026-11-03T11:03:19.658Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/cz-cubics
原文对照：https://npmcn.com/package/cz-cubics/?lang=original
项目主页：https://github.com/IshfaqAhmedProg/cz-cubics#readme
源码仓库：https://github.com/IshfaqAhmedProg/cz-cubics

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

- 包体积（解压后）：69.1 kB，9 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- peer 依赖：commitizen ^4
- 首次发布：2026-09-01T06:21:13.871Z
- 最新版本发布：2026-11-03T09:03:16.961Z
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

可定制的commizen适配器

## 安装

```sh
npm install cz-cubics
```

也可以使用：`pnpm add cz-cubics`、`yarn add cz-cubics`、`bun add cz-cubics`

## README

# cz-cubics

一个可定制的 [Commitizen](https://github.com/commitizen/cz-cli) 带有emoji前缀的常规提交消息的适配器，加上一个准备扩展 `commitlint` 配置。

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/cz-cubics)](https://bundlephobia.com/package/cz-cubics)

## 安装

```bash
pnpm add -D cz-cubics commitizen
```

将其注册为commizizen适配器 `package.json`：

```json
{
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-cubics"
    }
  }
}
```

或在 `.czrc`：

```json
{
  "path": "./node_modules/cz-cubics"
}
```

然后承诺：

```bash
pnpm commit
```

(假设一个 `"commit": "cz"` 脚本，或运行 `commitizen`/`git cz` 直接)

## 配置

Config从下面最近的文件中解析，通过 [`find-up`](https://www.npmjs.com/package/find-up) 顺序如下：

1.  `.czrc`
2.  `package.json`

的第一个匹配文件 `config["cz-cubics"]` 如果两者都存在，则关键获胜； `.czrc` 优先。

### 配置文件形状

**`.czrc`**

```json
{
  "config": {
    "cz-cubics": {
      "headFormat": "{type}{scope}: {subject}"
    }
  }
}
```

**`package.json`**

```json
{
  "config": {
    "commitizen": {
      "path": "node_modules/cz-cubics"
    },
    "cz-cubics": {
      "headFormat": "{type}{scope}: {subject}"
    }
  }
}
```

请注意 `cz-cubics` 坐着就像 **兄弟姐妹** 的 `commitizen` 下 `config`，而不是嵌套在其中。

自定义配置将被验证，无效类型，未知 `skipQuestions` 值，或未识别 `{token}`年代 `headFormat` 抛出错误，而不是静默失败或在第一个问题上失败。

### `CZCubicsConfig`

| 财产 | 类型 | 默认的 | 描述 |
| --- | --- | --- | --- |
| `types` | `CZCubicsCommitType[]` | 的内容 `defaultTypes.json` | 提供给用户的提交类型列表。 |
| `skipQuestions` | `string[]` | `[]` | 跳过以下任何一项： `scope`， `body`， `issues`， `breaking`。 `type` 和 `subject` 是必须的，不能跳过。 |
| `scopes` | `string[]` | \- | 在作用域自动完成提示符中显示预定义的作用域选择（query .js的选择数组）。 |
| `questions` | `Object` | \- | 覆盖生成的查询器问题。 |
| `subjectMaxLength` | `number` | `100` | 主题行的最大允许长度。 |
| `headFormat` | `string` | `"{emoji} {type}{scope}: {subject}"` | 提交头的模板。支持以下令牌。 |

### `CZCubicsCommitType`

每一项 `types` (在 `defaultTypes.json`)的形状为：

```json
{
  "name": "feat",
  "emoji": "✨",
  "description": "A new feature"
}
```

| 财产 | 类型 | 默认的 | 描述 |
| --- | --- | --- | --- |
| `name` | `string` | \- | 常规的提交类型关键字(例如： `feat`， `fix`）. |
| `emoji` | `string` | `""` | 表情符号显示在文字旁边，并通过 `{emoji}`。 |
| `description` | `string` | \- | 类型选择提示中显示的解释性文本。 |

### `headFormat` 令牌(`CZCubicsHeaderTokens`）

| 令牌 | 解析为 |
| --- | --- |
| `{emoji}` | 所选类型 `emoji`。 |
| `{type}` | 所选类型 `name`。 |
| `{scope}` | `(scope)` 如果输入了作用域，则为空。 |
| `{subject}` | 修剪过的主题行。 |

任何由省略的记号（例如，没有作用域）留下的连续空白将被折叠为单个空格。

### 例子 `.czrc`

```json
{
  "config": {
    "cz-cubics": {
      "types": [
        { "name": "feat", "emoji": "✨", "description": "A new feature" },
        { "name": "fix", "emoji": "🐛", "description": "A bug fix" }
      ],
      "scopes": ["api", "ui", "docs"],
      "skipQuestions": ["issues", "breaking"],
      "subjectMaxLength": 72,
      "headFormat": "{emoji} {type}{scope}: {subject}"
    }
  }
}
```

## 提交消息结构

最后的信息集合如下：

```
<head>

<body>

BREAKING CHANGE: <breakingBody>

<footer (issues)>
```

-   **头** =>建立从 `headFormat`，截断为终端的列宽度。
-   **身体** =>自由文本正文答案，绕到终端宽度。可以使用管道添加换行符 `|`
-   **打破** =>仅在提供破坏更改主体时包含。可以使用管道添加换行符 `|`
-   **页脚** =>问题引用，格式化通过 `formatIssues`。

空的部分被省略；结果是清除尾随空格。

## `commitlint` 集成

这个包自带 `commitlint.config.js`，消费者可以直接扩展这些规则，而不是复制规则：

```js
/** @type {import("@commitlint/types").UserConfig} */
module.exports = {
  extends: ["./node_modules/cz-cubics/commitlint.config.js"],
  // add or override rules here
};
```

当 `type` 在 `package.json` 是 `"module"` 也可以使用CJS版本

```js
/** @type {import("@commitlint/types").UserConfig} */
module.exports = {
  extends: ["./node_modules/cz-cubics/commitlint.config.cjs"],
  // add or override rules here
};
```

它包括:

-   `type-empty`:从来没有,
-   `subject-empty`:从来没有,
-   `subject-case`： `sentence-case`，总是强制执行。
-   `subject-max-length`： `100`，总是强迫，从你的决心 `subjectMaxLength` 配置。
-   `type-enum`：仅限于 `name` 的每一个条目 `types` 配置，因此只有您配置的提交类型通过。
-   `header-start-emoji`：总是强制头必须以一个开头 [Extended\_Pictographic](https://unicode.org/reports/tr51/) 角色（表情符号），与主角匹配 `{emoji}` 令牌的 `headFormat`。
-   `header-has-emoji`：默认关闭 `0`)相同的表情符号检测，但检查整个标题行，而不仅仅是前导符号。启用它（严重性） `2`), `"always"` 如果你想让表情符号在标题的任何地方被允许，而不是只在开头。
-   一个 `parserPreset` 谁的 `headerPattern` 和 `headerCorrespondence` 是 **动态构建从您的解析 `headFormat`**，而不是硬编码。这意味着:
    -   改变 `headFormat` 在你的配置中自动更改过滤器解析和验证的内容。
    -   所需令牌(`{type}`， `{subject}`)使用匹配策略，即使其中一个是空的，仍然可以让整个头解析成功
    -   可选令牌(`{emoji}`， `{scope}`)在省略时被正确地视为缺席，而不需要占位符值。

### 需求

`cz-cubics/commitlint.config.js` 是一个普通的配置对象，运行时不依赖于任何提交包本身。然而，要真正检测提交，你需要 `@commitlint/cli` 安装 **在你自己的项目中**，因为这是读取和执行配置：

```bash
pnpm add -D @commitlint/cli
```

### 沙哑的钩

把它连接起来 `.husky/commit-msg`：

```sh
pnpm commitlint --edit "$1"
```

确保钩子文件是可执行的(`chmod +x .husky/commit-msg`)和 `core.hooksPath` 点 `.husky` (由自动设置 `prepare: "husky"` 脚本)。

## 许可证

麻省理工学院

## 特别感谢

-   [ngryman / cz-emoji](https://github.com/ngryman/cz-emoji)：基于表情符号的常规提交类型的核心思想是这个适配器的基础。
-   [commitizen / cz-cli](https://github.com/commitizen/cz-cli)：此包插入的适配器框架。

## 常见问题

### cz-cubics 是什么？

可定制的commizen适配器

### 如何安装 cz-cubics？

在项目目录运行 npm install cz-cubics，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：commitizen（^4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### cz-cubics 支持 TypeScript 吗？

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

### cz-cubics 支持 ESM 还是 CommonJS？

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

### cz-cubics 需要什么版本的 Node\.js？

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

### cz-cubics 可以商用吗？

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

### cz-cubics 还在维护吗？

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