# @cloudcannon/reader 中文文档

规范地址：https://npmcn.com/package/%40cloudcannon/reader/

版本：1\.1\.6
npm 元数据更新时间：2026-04-17T02:51:26.785Z
中文译文更新时间：2026-11-10T02:51:55.139Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：30.6 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：11 个
- 首次发布：2021-08-31T21:37:21.942Z
- 最新版本发布：2024-12-03T01:18:42.389Z
- 近 30 天下载量：2922（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 0 个）

## 中文简介

解析配置,文件和文件夹结构,以创建 JSON 文件,其中包含使用任何静态站点生成器制作的站点信息.

## 安装

```sh
npm install @cloudcannon/reader
```

也可以使用：`pnpm add @cloudcannon/reader`、`yarn add @cloudcannon/reader`、`bun add @cloudcannon/reader`

## README

# 阅读器

创建 [云冈](https://cloudcannon.com/) 为任何静态的站点建立信息 现场发电机.

此工具运行在您的 SSG 构建之后, 读取您的配置以查找页面, 收藏, 以及 数据文件以创建用于自动将网站与CloudCannon集成的JSON文件. 这个 JSON 文件写入 `_cloudcannon/info.json`。 。 。 .

[![version badge](https://img.shields.io/npm/v/@cloudcannon%2Freader?logo=npm)](https://www.npmjs.com/package/@cloudcannon%2Freader) [![downloads badge](https://img.shields.io/npm/dt/@cloudcannon%2Freader)](https://www.npmjs.com/package/@cloudcannon%2Freader)

* * *

-   [安装](https://npmcn.com/package/%40cloudcannon/reader/#readme-installation)
-   [配置](https://npmcn.com/package/%40cloudcannon/reader/#readme-configuration)
-   [文档](https://npmcn.com/package/%40cloudcannon/reader/#readme-documentation)
    -   [来源](https://npmcn.com/package/%40cloudcannon/reader/#readme-source)
    -   [产出](https://npmcn.com/package/%40cloudcannon/reader/#readme-output)
    -   [数据](https://npmcn.com/package/%40cloudcannon/reader/#readme-data)
    -   [收款](https://npmcn.com/package/%40cloudcannon/reader/#readme-collections)
    -   [云冈](https://npmcn.com/package/%40cloudcannon/reader/#readme-cloudcannon)
-   [解析器](https://npmcn.com/package/%40cloudcannon/reader/#readme-parsers)
-   [发展](https://npmcn.com/package/%40cloudcannon/reader/#readme-development)
-   [许可证](https://npmcn.com/package/%40cloudcannon/reader/#readme-license)

* * *

## 安装

**你不需要安装任何东西** 在CloudCannon建设时 此工具是自动的 在您的网站建成前安装。 这为您提供了最新的支持,新的功能和修正 他们被释放.

**需要时**,您可以手动安装工具,测试整合和诊断问题.

```bash
npm install --global @cloudcannon/reader
```

这让你可以访问 `cloudcannon-reader` 二进制.

使用量

> 要生成 JSON 文件 `_cloudcannon/info.json`数字 :
> 
> ```sh
> $ cloudcannon-reader
> ```
> 
> 打印使用细节 :
> 
> ```sh
> $ cloudcannon-reader --help
> 
> Usage
>   $ cloudcannon-reader [options]
> 
> Options
>   --version     Print the current version
>   --config, -c  Use a specific configuration file
>   --output, -o  Write to a different location than .
>   --quiet, -q   Disable logging
> 
> Environment
>   CLOUDCANNON_CONFIG_PATH  Use a specific configuration file
> 
> Examples
>   $ cloudcannon-reader --config "cloudcannon.dev.config.json"
>   $ cloudcannon-reader --output "public"
>   $ CLOUDCANNON_CONFIG_PATH=src/cloudcannon.config.js cloudcannon-reader
> ```

* * *

## 配置

配置文件应在根目录中( 或您运行的同一目录) `cloudcannon-reader`) (中文(简体) ). 使用此顺序中的第一个支持文件 :

-   `cloudcannon.config.json`
-   `cloudcannon.config.yaml`
-   `cloudcannon.config.yml`
-   `cloudcannon.config.js`
-   `cloudcannon.config.cjs`

或者,使用与 `CLOUDCANNON_CONFIG_PATH` 环境变量或 `--config` 命令行选项 :

```sh
$ CLOUDCANNON_CONFIG_PATH=src/cloudcannon.config.js cloudcannon-reader
$ cloudcannon-reader --config "src/cloudcannon.config.js"
```

您的全球 CloudCannon 配置也设置在这个文件中, 因为它被用作一个基础 生成 `_cloudcannon/info.json` (用来整合你的网站与CloudCannon).

示例内容 `cloudcannon.config.cjs`数字 :

```javascript
module.exports = {
  // Global CloudCannon configuration
  _inputs: {
    title: {
      type: 'text',
      comment: 'The title of your page.'
    }
  },
  _select_data: {
    colors: ['Red', 'Green', 'Blue']
  },

  // Read from ./src instead of .
  source: 'src',

  // Write to ./output/_cloudcannon/info.json instead of ./_cloudcannon/info.json
  output: 'output',

  // Populates the sidebar navigation and provides metadata for the editor
  collections_config: {
    people: {
      // Reads the contents of each file in this directory
      path: 'content/people',

      // The URL template for items in this collection
      url: '/people/{department|slugify}/[slug]/',

      // Tells CloudCannon this collection produces output files
      output: true

      // CloudCannon collection-level configuration
      name: 'Personnel',
      _enabled_editors: ['data']
    },
    posts: {
      // Reads the contents of each file in this directory
      path: '_posts',

      // How to parse the files in this collection
      parser: 'front-matter',

      // The URL function for items in this collection
      url: (filePath, parsed, { filters }) => {
        const year = new Date(parsed.date).getFullYear();
        const slug = filters.slugify(parsed.title || '');
        return `/posts/${year}/${slug}/`;
      },

      // Tells CloudCannon this collection produces output files
      output: true
    },
    pages: {
      // Tells CloudCannon to navigate to this path for this collection
      path: '',

      // Limits files read to these patterns (relative to path)
      glob: ['**/*.md', '*.html'],

      // Tells CloudCannon to only show successfully parsed files for this collection
      // Useful for excluding other collections when using '' as path
      filter: 'strict',

      // Tells CloudCannon this collection produces output files
      output: true
    },
    data: {
      // Reads the contents of each file in this directory
      path: 'data',

      // How to parse the files in this collection
      parser: (filePath, raw, { parsers, filters }) => {
        const parsed = parsers['front-matter'].parse(raw);
        const slug = filters.slugify(parsed.title || '');
        return { ...data, slug };
      }
    }
  },

  // Generates the data for select and multiselect inputs matching these names
  data_config: {
    authors: {
      // Reads the contents of this file
      path: 'data/authors.csv'
    },
    offices: {
      // Reads the contents of each file in this directory
      path: 'data/offices',
      parser: 'json'
    }
  }
};
```

* * *

## 文档

这个 `_cloudcannon/info.json` 文件最初包含您的配置内容. `cloudcannon-reader` 然后生成用于 `collections`, (中文(简体) ), `data`, (中文(简体) ), `time`, (中文(简体) ), `version`,以及 `cloudcannon`。 。 。 .

### 来源

这个 `source` 设置更改从另一个文件夹读取的地方。 这个 `path` 收藏项的值相对 `source`默认为 `'.'`。 。 。 .

### 产出

这个 `output` 设置更改要写入的地方 `_cloudcannon` 文件夹中包含 `info.json`默认为 `'.'`。 。 。 .

### 数据

这个 `data_config` 定义数据文件应如何读取和解析到 JSON 代表。 默认为 `{}`。 。 。 .

```json
{
  "data_config": {
    "locations": {
      "path": "data/locations.csv"
    },
    "offices": {
      "path": "data/offices",
      "parser": "front-matter"
    }
  }
}
```

每个数据集配置中可用的密钥为:

`path`

> 这个 `path` 是指:
> 
> -   本数据集文件存储的最顶端文件夹 .
> -   包含数据的文件 .
> 
> 这两种选择都与 `source`。 。 。 .

`parser` (可选)

> 这个 `parser` 字段应说明 [解析器](https://npmcn.com/package/%40cloudcannon/reader/#readme-parsers) 您想要在此数据集中读取文件.

### 收款

这个 `collections_config` 对象定义收藏及其文件应如何被读取和解析到 JSON 表示式。 默认为 `{}`。 。 。 .

```json
{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "parser": "yaml",
      "url": "/posts/{category|slugify}/[slug].html"
    }
  }
}
```

匹配 CloudCannon 的收藏级配置格式,此格式也在此设置(例如. `name`, (中文(简体) ), `_enabled_editors`, (中文(简体) ), `add_options`) (中文(简体) ).

每个收藏配置中可用的密钥有:

`path`

> 这个 `path` 是存储此收藏中文件的最上层文件夹 。 这是相对 `source`。 。 。 .

`glob` (可选)

> 这个 `glob` 是包含图案的字符串或字符串阵列,用于过滤解析到此收藏的文件。 球是相对 `path`。模式与 [缩写](https://github.com/micromatch/picomatch#basic-globbing)。如果设置为数组,文件只需匹配一个被解析的 glob 模式.
> 
> ```javascript
> glob: ['**/*.md', '**/*.html'] // All .md and .html files
> ```
> 
> 用于查找文件而不是 `path`,但是仍然需要路径作为收集的基础路径.
> 
> -   `'./src/*.md'` 匹配 `.md` 文档中 `src` 文件夹.
> -   `'**/*.html'` 匹配 `.html` 任何文件夹或子文件夹中的文件.
> -   `['**/*.md', './pages/*.html']` 匹配 `.md` 任何文件夹中的文件,或 `.html` 文档中 `pages` 文件夹.

`url` (可选)

> 这个 `url` 用于构建 `url` 字段中的项目。 类似于许多 SSG 中的 permarink. 可以是字符串或函数. 默认为 `''`。 。 。 .
> 
> 支持函数的有: `.js` 或者说 `.cjs` 文档。 给定文件路径,解析文件内容和带有过滤器的对象 `buildUrl` 函数和 `collection_config` 作为参数。 返回值应该是斜线前缀的 URL 字符串 .
> 
> ```javascript
> url: (filePath, content, { filters, buildUrl, collectionConfig }) => {
>   if (content.permalink) {
>     // Returns a lower case permalink front matter field
>     return filters.lowercase(content.permalink);
>   }
> 
>   // Falls back to processing a default url template
>   // Takes filePath, content, and a collections_config entry
>   return buildUrl(filePath, content, { ...collectionsConfig, url: '/[slug]/' });
> }
> ```
> 
> 字符串被用作构建URL的模板. 有两种类型的占位符,即文件和数据。 支持导致空值的占位符 。 URL中的相继鞭打被收缩为一.
> 
> ```javascript
> url: '/blog/{date|year}/[slug]/'
> ```
> 
> 文件占位符总是可用的,由 `cloudcannon-reader`数字 :
> 
> -   `[path]` 是文件的全部路径,相对于 `source`。 。 。 .
> -   `[base_path]` 是文件的路径,不包括文件名,相对于站点 `source`。 。 。 .
> -   `[slug]` 是文件名,不包括扩展名。 如果结果为“ index” , 是空字符串 .
> -   `[filename]` 是文件名,包括扩展名.
> -   `[ext]` 是最后一个扩展,包括 `.`。 。 。 .
> -   `[relative_path]` 是文件的完整路径, 相对于收藏 `path`。 。 。 .
> -   `[relative_base_path]` 是文件的路径,不包括文件名,相对于收藏 `path`。 。 。 .
> -   `[full_slug]` 是用于 `[relative_base_path]/[slug]`
> 
> 数据占位符是从文件的前题或数据值中被覆盖的,并支持一些过滤器:
> 
> -   `{title}` 这是 `title` 从文件内部.
> -   `{id}` 这是 `id` 从文件内部.
> -   `{title|lowercase}` 实值 `title` 从文件内部,小写.
> -   `{category|slugify}` 实值 `category` 从文件内部,被击出.
> -   `{tag|slugify|uppercase}` 实值 `tag` 从文件内部,被打出,然后是大案.
> -   `{date|year}` 实值 `date` 从文件内部, 取出4位数的年份.
> -   `{date|month}` 实值 `date` 从文件内部取出 2 位数月.
> -   `{date|day}` 实值 `date` 从文件内部取出 2 位数的一天.

`parser` (可选)

> 这个 `parser` 字段应说明 [解析器](https://npmcn.com/package/%40cloudcannon/reader/#readme-parsers) 您想要用来读取此收藏中的文件.
> 
> ```javascript
> parser: 'front-matter'
> ```

### 云冈

设定全局 [云罐配置](https://cloudcannon.com/documentation/edit/editing/configuration/#configuration) 作为您的顶级密钥 `cloudcannon-reader` 配置和它们会被复制到 `_cloudcannon/info.json`。 。 。 .

CloudCannon然后在应用程序中读取这些并应用到您的编辑界面中. 其中包括:

-   `collection_groups`
-   `editor`
-   `source_editor`
-   `_enabled_editors`
-   `_inputs`
-   `_editables`
-   `_select_data`
-   `_structures`

* * *

## 解析器

解析器定义 `cloudcannon-reader` 将您的文件处理到 JSON 中 `info.json`中,您可以设置数据和收藏的解析器 `data_config` 财务报告和审定财务报表 `collections_config`。 。 。 .

这些是覆盖的现有解析器和默认文件扩展名 :

-   `csv` (单位:千美元)`.csv`(中文(简体) )
-   `front-matter` (单位:千美元)`.md`, (中文(简体) ), `.mkd`, (中文(简体) ), `.markdown`, (中文(简体) ), `.html`, (中文(简体) ), `.htm`(中文(简体) )
-   `json` (单位:千美元)`.json`(中文(简体) )
-   `properties` (单位:千美元)`.properties`(中文(简体) )
-   `toml` (单位:千美元)`.toml`(中文(简体) )
-   `yaml` (单位:千美元)`.yaml`, (中文(简体) ), `.yml`(中文(简体) )

支持函数的有: `.js` 或者说 `.cjs` 文档。 给定文件路径、 原始文件内容和以解析器和过滤器作为参数的对象 。 返回值应为代表该文件的对象.

`cloudcannon-reader` 如果找不到合适的解析器, 则退出出错 .

* * *

## 发展

安装依赖性 :

```sh
$ npm i
```

运行测试 :

```sh
$ npm test
$ npm run test:watch
$ npm run test:coverage
```

林特代码 :

```sh
$ npm run lint
```

将此软件包链接到本地, 在站点文件夹中测试, 然后在您的站点文件夹中运行 :

```sh
$ npm link
$ cd ../my-ssg-site
$ cloudcannon-reader
```

## 许可证

公务员制度委员会

## 常见问题

### @cloudcannon/reader 是什么？

解析配置,文件和文件夹结构,以创建 JSON 文件,其中包含使用任何静态站点生成器制作的站点信息\.

### 如何安装 @cloudcannon/reader？

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

### @cloudcannon/reader 支持 TypeScript 吗？

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

### @cloudcannon/reader 支持 ESM 还是 CommonJS？

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

### @cloudcannon/reader 可以商用吗？

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

### @cloudcannon/reader 的下载量有多少？

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

### @cloudcannon/reader 还在维护吗？

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