# @getkist/action-nunjucks 中文文档

规范地址：https://npmcn.com/package/%40getkist/action-nunjucks/

版本：2\.0\.33
npm 元数据更新时间：2026-10-09T08:06:51.654Z
中文译文更新时间：2026-11-16T13:12:21.114Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：153 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：3 个
- peer 依赖：kist \>=0\.1\.58
- 首次发布：2026-02-08T21:07:41.614Z
- 最新版本发布：2026-10-09T08:06:51.462Z
- 近 30 天下载量：2208（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

Jinja/ Nunjucks 模板为 kist 提供动作, 并提供单文件和目录模式支持

## 安装

```sh
npm install @getkist/action-nunjucks
```

也可以使用：`pnpm add @getkist/action-nunjucks`、`yarn add @getkist/action-nunjucks`、`bun add @getkist/action-nunjucks`

## README

# @ getkist/ action- nunjucks (英语)

[![npm version](https://img.shields.io/npm/v/@getkist/action-nunjucks?style=flat-square&logo=npm&logoColor=FFFFFF&labelColor=5e4d34&color=5e4d34)](https://www.npmjs.com/package/@getkist/action-nunjucks) [![CI](https://img.shields.io/github/actions/workflow/status/getkist/kist-action-nunjucks/ci.yml?style=flat-square&logo=githubactions&logoColor=FFFFFF&label=CI&labelColor=5e4d34&color=5e4d34)](https://github.com/getkist/kist-action-nunjucks/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/codecov/c/github/getkist/kist-action-nunjucks?style=flat-square&logo=codecov&logoColor=FFFFFF&label=Coverage&labelColor=5e4d34&color=5e4d34)](https://codecov.io/gh/getkist/kist-action-nunjucks) [![License: MIT](https://img.shields.io/badge/License-MIT-5e4d34?style=flat-square)](https://opensource.org/licenses/MIT) [![kist plugin](https://img.shields.io/badge/kist-plugin-5e4d34?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyTDIgN3Y2YzAgNS41NSAzLjg0IDEwLjc0IDEwIDEyIDYuMTYtMS4yNiAxMC02LjQ1IDEwLTEyVjdMMTIgMnoiLz48L3N2Zz4=)](https://github.com/getkist/kist)

Jinja/ Nunjucks 模板为 [键](https://github.com/getkist/kist) 构建工具.

## 特征

-   QQ 文件的 Render Nunjucks 模板
-   📁 **目录模式** - 批量渲染整个文件夹保存结构
-   QQ 从 YAML/ JSON 文件装入上下文数据
-   \* 配置 Nunjucks 行为(自动逃生、修剪、脱口而出)
-   自定义输出编码支持
-   用于文档站点、静态页面和代码源

## 安装

```bash
npm install --save-dev @getkist/action-nunjucks
```

## 快速启动

### 单文件模式

```yaml
pipeline:
    stages:
        - name: render
          steps:
              - name: render-page
                action: TemplateRenderAction
                options:
                    templatePath: ./templates/page.njk
                    outputPath: ./dist/page.html
                    context:
                        title: "Welcome"
```

### 目录模式

在保存文件夹结构的同时将所有模板编成目录 :

```yaml
pipeline:
    stages:
        - name: render
          steps:
              - name: render-templates
                action: TemplateRenderAction
                options:
                    inputDir: ./src/templates
                    outputDir: ./dist
                    pattern: "**/*.html.jinja"
                    excludePatterns:
                        - "_*.jinja"
                        - "partials/**"
                    stripExtension: ".jinja"
                    context:
                        siteName: "My Site"
```

这使得:

-   `src/templates/index.html.jinja` → `dist/index.html`
-   `src/templates/about/team.html.jinja` → `dist/about/team.html`
-   跳过 `_base.jinja` 财务报告和审定财务报表 `partials/` 文件

## 文档

-   **[使用指南](https://npmcn.com/package/%40getkist/action-nunjucks/doc/usage.md)** - YAML和方案实例
-   **[配置](https://npmcn.com/package/%40getkist/action-nunjucks/doc/configuration.md)** - 所有可用的选项
-   **[实例](https://npmcn.com/package/%40getkist/action-nunjucks/doc/examples.md)** - 真实世界使用案例
-   **[API 参考](https://npmcn.com/package/%40getkist/action-nunjucks/doc/api.md)** - 生成类型文件
-   **[解决问题](https://npmcn.com/package/%40getkist/action-nunjucks/doc/troubleshooting.md)** - 共同问题和解决办法
-   **[业绩指南](https://npmcn.com/package/%40getkist/action-nunjucks/doc/performance.md)** - 优化提示

## 行动

### 模板渲染动作

有可选上下文文件和Nunjucks配置的Renders Nunjucks模板.

#### 单一文件模式选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `templatePath` | 字符串 | 对 | 模板文件路径 |
| `outputPath` | 字符串 | 对 | 输出文件路径 |
| `context` | 对象 | 没有 | 模板上下文数据 |
| `contextFiles` | 字符串 \[\] | 没有 | 要合并的 YAML/ JSON 文件 |
| `searchPaths` | 字符串 \[\] | 没有 | 包括的模板搜索路径 |
| `autoescape` | 布尔 | 没有 | 启用 HTML 出逃 |
| `trimBlocks` | 布尔 | 没有 | 从区块调整新线 |
| `lstripBlocks` | 布尔 | 没有 | 从块中剥去领导空白 |
| `outputEncoding` | 字符串 | 没有 | 文件编码( 默认: utf8) |

#### 目录模式选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `inputDir` | 字符串 | 对 | 包含模板的源目录 |
| `outputDir` | 字符串 | 对 | 已渲染文件输出目录 |
| `pattern` | 字符串 | 没有 | Glob 模式( 默认 ): `**/*.html.jinja`(中文(简体) ) |
| `excludePatterns` | 字符串 \[\] | 没有 | 应予排除的模式(例如部分) |
| `stripExtension` | 字符串 | 没有 | 删除扩展( 默认 ): `.jinja`(中文(简体) ) |
| `context` | 对象 | 没有 | 共享所有模板的上下文 |
| `contextFiles` | 字符串 \[\] | 没有 | 要合并的 YAML/ JSON 文件 |
| `searchPaths` | 字符串 \[\] | 没有 | 包括的模板搜索路径 |
| `autoescape` | 布尔 | 没有 | 启用 HTML 出逃 |
| `trimBlocks` | 布尔 | 没有 | 从区块调整新线 |
| `lstripBlocks` | 布尔 | 没有 | 从块中剥去领导空白 |
| `outputEncoding` | 字符串 | 没有 | 文件编码( 默认: utf8) |

## 发展

```bash
npm run build        # Compile TypeScript
npm run test         # Run tests
npm run lint         # Check code quality
npm run docs         # Generate API documentation
npm run format       # Format code with Prettier
```

## 所需资源

-   节点.js 22.0.0
-   npm = 10.0.0 (韩语)

## 许可证

麻省理工学院

## 常见问题

### @getkist/action-nunjucks 是什么？

Jinja/ Nunjucks 模板为 kist 提供动作, 并提供单文件和目录模式支持

### 如何安装 @getkist/action-nunjucks？

在项目目录运行 npm install @getkist/action-nunjucks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：kist（\>=0\.1\.58）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @getkist/action-nunjucks 支持 TypeScript 吗？

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

### @getkist/action-nunjucks 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @getkist/action-nunjucks 需要什么版本的 Node\.js？

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

### @getkist/action-nunjucks 可以商用吗？

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

### @getkist/action-nunjucks 的下载量有多少？

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

### @getkist/action-nunjucks 还在维护吗？

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

