# @c-time/frelio-data-json-generator 中文文档

规范地址：https://npmcn.com/package/%40c-time/frelio-data-json-generator/

版本：3\.6\.1
npm 元数据更新时间：2026-11-07T16:08:42.251Z
中文译文更新时间：2026-11-08T22:27:35.757Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40c-time/frelio-data-json-generator
原文对照：https://npmcn.com/package/%40c-time/frelio-data-json-generator/?lang=original
项目主页：https://github.com/c-time/frelio#readme
源码仓库：https://github.com/c-time/frelio

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

- 包体积（解压后）：526 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：5 个
- 首次发布：2026-03-30T02:20:23.258Z
- 最新版本发布：2026-11-07T16:08:42.089Z
- 近 30 天下载量：2614（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

从 FrelioBuildDataRepipe 中生成 FrelioDataJson 并增加建设支持

## 安装

```sh
npm install @c-time/frelio-data-json-generator
```

也可以使用：`pnpm add @c-time/frelio-data-json-generator`、`yarn add @c-time/frelio-data-json-generator`、`bun add @c-time/frelio-data-json-generator`

## README

# @c-time/frelio-data-json-生成器

弗列利奥·布利德·达塔·杰森。

## (单位:千美元)

`@c-time/frelio-data-json-generator` GitHub 动作 QQCMS HTML ~ JSON ~ (FreliodataJson) ~~。

### 特徴

-   **差分ビルド**翻译:
-   **フルリビルド**页:1`--full-rebuild` オプション
-   **依存マップ**时间轴:
-   **エラーレポート**时间轴:
-   **ドライラン**页:1`--dry-run` オプション

## インストール

```bash
npm install @c-time/frelio-data-json-generator
```

## CLI 国家

```bash
# 差分ビルド（デフォルト: origin/main...HEAD）
npx tsx scripts/generate-data-json.ts

# フルリビルド（全ファイル再生成）
npx tsx scripts/generate-data-json.ts --full-rebuild

# ドライラン（ファイル出力せずレポートのみ）
npx tsx scripts/generate-data-json.ts --dry-run

# 差分範囲を指定
npx tsx scripts/generate-data-json.ts --diff-range "origin/develop...HEAD"

# ログレベル
npx tsx scripts/generate-data-json.ts --log-level debug
npx tsx scripts/generate-data-json.ts --log-level info   # デフォルト
npx tsx scripts/generate-data-json.ts --log-level quiet
```

## プログラム使用例

```typescript
import {
  generateDataJson,
  NodeFileSystem,
  getGitDiff,
} from '@c-time/frelio-data-json-generator'
import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs'
import { dirname, join } from 'path'

// レシピと依存マップを読み込み
const recipe = JSON.parse(
  readFileSync('frelio-data/admin/recipes/build-data-recipe.json', 'utf-8')
)
const dependencyMap = JSON.parse(
  readFileSync('frelio-data/admin/dependency-map.json', 'utf-8')
)

// Git diff を取得
const gitDiff = await getGitDiff('origin/main...HEAD')

// FrelioDataJson を生成
const result = await generateDataJson({
  recipe,
  dependencyMap,
  gitDiff,
  fileSystem: new NodeFileSystem(),
  contentRootPath: 'frelio-data/site',
  outputRootPath: 'frelio-data/generated/data-json',
  options: {
    fullRebuild: false,
    dryRun: false,
    logLevel: 'info',
  },
})

const OUTPUT_ROOT = 'frelio-data/generated/data-json'

// 結果を出力
for (const output of result.outputs) {
  const fullPath = join(OUTPUT_ROOT, output.path)

  if (output.content.type === 'delete') {
    // 削除
    unlinkSync(fullPath)
  } else {
    // 作成/更新
    mkdirSync(dirname(fullPath), { recursive: true })
    writeFileSync(fullPath, JSON.stringify(output.content, null, 2))
  }
}

// レポートを出力
writeFileSync(
  'frelio-data/generated/report.json',
  JSON.stringify(result.report, null, 2)
)

console.log(`Updated: ${result.report.stats.updated}`)
console.log(`Deleted: ${result.report.stats.deleted}`)
console.log(`Errors: ${result.report.stats.errors}`)
```

## カスタムフィールド

レシピの `customFields` JSON 3 つのタイプがあります。

### QQ( 变换)

ソース式とフォーマット関数でフィールド値を変換・整形します。

```json
{ "field": "formattedDate", "source": "{$this.publishedAt}", "type": "date", "format": "YYYY年M月D日" }
{ "field": "excerpt", "source": "{$this.body}", "type": "truncate", "length": 100 }
{ "field": "fullTitle", "source": "{$this.title} - {$this.subtitle}" }
```

**フォーマットタイプ一覧:**

| カテゴリ | タイプ | 説明 |
| --- | --- | --- |
| 文字列 | `string`, (中文(简体) ), `slug`, (中文(简体) ), `lowercase`, (中文(简体) ), `uppercase`, (中文(简体) ), `truncate` | 文字列変換 |
| HTML 语言 | `stripHtml`, (中文(简体) ), `escape`, (中文(简体) ), `toc` | HTML QQ 语言 |
| 数値・日付 | `date`, (中文(简体) ), `number` | フォーマット指定可 |
| 配列 | `count`, (中文(简体) ), `first`, (中文(简体) ), `last`, (中文(简体) ), `join` | 配列操作 |
| その他 | `default`, (中文(简体) ), `url` | 乌尔勒 |

### リレーションリスト型(关系论)

任意のコンテンツタイプのリストを参照・埋め込みます。

```json
{
  "field": "relatedArticles",
  "type": "relationList",
  "contentTypeId": "article",
  "limit": 5,
  "sort": { "field": "publishedAt", "direction": "desc" },
  "filters": [{ "field": "status", "operator": "eq", "value": "published" }]
}
```

### (持续)

コンテンツに依存しない固定値を出力します。文字列・数値・真偽値・配列・オブジェクト等の任意の値を設定可能です。

```json
{ "field": "siteName", "type": "constant", "value": "My Site" }
{ "field": "baseUrl", "type": "constant", "value": "https://example.com" }
{ "field": "maxItems", "type": "constant", "value": 10 }
{ "field": "features", "type": "constant", "value": ["blog", "news"] }
```

## 出力形式

### 弗列利奥达塔·杰森

```json
{
  "type": "update",
  "template": "article/detail.html",
  "outputFile": "articles/my-article.json",
  "data": {
    "contentId": "123e4567-e89b-12d3-a456-426614174000",
    "slug": "my-article",
    "title": "記事タイトル",
    "body": "<p>記事本文...</p>"
  }
}
```

| フィールド | 説明 |
| --- | --- |
| `type` | `"update"` または `"delete"` |
| `template` | 使用するテンプレートのパス |
| `outputFile` | 出力先のパス |
| `data` | テンプレートに渡すデータ |

### 报告.json

```json
{
  "generatedAt": "2026-03-28T10:00:00.000Z",
  "mode": "incremental",
  "dryRun": false,
  "stats": {
    "updated": 15,
    "deleted": 2,
    "skipped": 0,
    "errors": 1
  },
  "outputs": [
    { "path": "articles/my-article.json", "status": "updated" },
    { "path": "articles/old-article.json", "status": "deleted" }
  ],
  "errors": [
    {
      "code": "RELATION_NOT_FOUND",
      "outputPath": "articles/broken.json",
      "contentId": "abc-123",
      "field": "relatedCategory",
      "message": "リレーション先 'category/xyz' が見つかりません"
    }
  ],
  "warnings": [
    {
      "code": "EMPTY_LIST",
      "outputPath": "tags/empty-tag.json",
      "message": "リストが空です: tags"
    }
  ]
}
```

## 処理フロー

```
1. Git diff から変更ファイルを検出（または --full-rebuild で全件）
2. dependency-map を使って再生成スコープを計算
3. templateIncludes でパーツ変更の影響を拡張
4. 既存出力をスキャンして削除検出に備える
5. 必要なコンテンツをロード
6. レシピに従って FrelioDataJson を生成
7. 削除対象を検出（今回出力されなかったファイル）
8. レポートを生成
```

## エラーハンドリング

一部のコンテンツが生成できなくても、処理は最後まで継続します。 エラーは `report.json` の `errors` 校对:Soup。

### エラーコード

| コード | 説明 | 対処 |
| --- | --- | --- |
| `RELATION_NOT_FOUND` | リレーション先が見つからない | スキップして継続 |
| `CONTENT_NOT_FOUND` | コンテンツファイルが見つからない | スキップして継続 |
| `INVALID_TEMPLATE_VAR` | 输出 Path QQ | スキップして継続 |
| `INVALID_JSON` | JSON(美国) | スキップして継続 |
| `FILTER_ERROR` | フィルター条件が不正 | スキップして継続 |
| `CIRCULAR_REFERENCE` | 循環参照を検出 | スキップして継続 |
| `INVALID_OUTPUT_PATH` | パス禁止文字・空文字 | **出力しない** |
| `DUPLICATE_OUTPUT_PATH` | 同一パスが複数回生成 | **最初の1つのみ出力** |

### 警告コード

| コード | 説明 |
| --- | --- |
| `EMPTY_LIST` | リストが空 |
| `TRUNCATED_RELATION` | 限制 |
| `DEFAULT_VALUE_USED` | デフォルト値を使用 |

## オプション

| オプション | CLI 国家 | 説明 | デフォルト |
| --- | --- | --- | --- |
| `fullRebuild` | `--full-rebuild` | 全ファイル再生成 | `false` |
| `dryRun` | `--dry-run` | ファイル出力せずレポートのみ | `false` |
| `logLevel` | `--log-level` | qq (调试/ info/ 静音) | `info` |

## API —— ——

### 生成数据Json( 输入)

弗列利奥达塔杰森。

```typescript
function generateDataJson(
  input: GenerateDataJsonInput
): Promise<GenerateDataJsonResult>
```

#### 入力

| パラメータ | 页:1 | 説明 |
| --- | --- | --- |
| `recipe` | `FrelioBuildDataRecipe` | ビルドレシピ |
| `dependencyMap` | `FrelioDependencyMap` | 依存マップ |
| `gitDiff` | `GitDiffInfo` | {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 |
| `fileSystem` | `FileSystemPort` | ファイルシステム |
| `contentRootPath` | `string` | コンテンツ読み込み元パス |
| `outputRootPath` | `string` | 出力先ルートパス |
| `options` | `GenerateDataJsonOptions` | オプション |

#### 出力

| フィールド | 页:1 | 説明 |
| --- | --- | --- |
| `outputs` | `OutputFile[]` | 生成されたファイル一覧 |
| `report` | `GenerationReport` | ビルドレポート |

### 获取 GitDiff( diff Range)

指定した範囲の {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢。

```typescript
function getGitDiff(diffRange: string): Promise<GitDiffInfo>
```

### 剖析GitDiff( diffText)

`git diff --name-status` の出力をパースします。

```typescript
function parseGitDiff(diffText: string): GitDiffInfo
```

### 节点文件系统

节点.js `FileSystemPort` 実装。

```typescript
class NodeFileSystem implements FileSystemPort {
  readFile(path: string): Promise<string>
  exists(path: string): Promise<boolean>
  listFiles(pattern: string): Promise<string[]>
}
```

## GitHub 动作QQ

### 差分ビルド

```yaml
name: Generate Data JSON

on:
  push:
    branches: [staging-*]
    paths:
      - 'frelio-data/site/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 差分比較のため

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx tsx scripts/generate-data-json.ts

      - name: Commit generated files
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add frelio-data/generated/
          git commit -m "chore: generate data JSON" || true
          git push
```

### フルリビルド(タグベース)

```yaml
name: Full Rebuild Data JSON

on:
  push:
    tags:
      - 'rebuild-*'

jobs:
  rebuild:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx tsx scripts/generate-data-json.ts --full-rebuild
```

## 依存関係

```
@c-time/frelio-data-json-generator
├── @c-time/frelio-data-json         # 出力型 (FrelioDataJson)
├── @c-time/frelio-data-json-recipe  # レシピ型 (FrelioBuildDataRecipe)
└── @c-time/frelio-dependency-map    # スコープ選定 (FrelioDependencyMap)
```

## ライセンス

私营

## 常见问题

### @c-time/frelio-data-json-generator 是什么？

从 FrelioBuildDataRepipe 中生成 FrelioDataJson 并增加建设支持

### 如何安装 @c-time/frelio-data-json-generator？

在项目目录运行 npm install @c-time/frelio-data-json-generator，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 frelio-data-json-generator，可以用 npx frelio-data-json-generator 直接运行。

### @c-time/frelio-data-json-generator 支持 TypeScript 吗？

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

### @c-time/frelio-data-json-generator 支持 ESM 还是 CommonJS？

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

### @c-time/frelio-data-json-generator 需要什么版本的 Node\.js？

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

### @c-time/frelio-data-json-generator 可以商用吗？

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

### @c-time/frelio-data-json-generator 的下载量有多少？

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

### @c-time/frelio-data-json-generator 还在维护吗？

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