# @kiln-ssg/kiln 中文文档

规范地址：https://npmcn.com/package/%40kiln-ssg/kiln/

版本：0\.5\.2
npm 元数据更新时间：2026-11-01T12:50:03.970Z
中文译文更新时间：2026-11-01T15:49:55.589Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40kiln-ssg/kiln
原文对照：https://npmcn.com/package/%40kiln-ssg/kiln/?lang=original
项目主页：https://github.com/hakula139/kiln
源码仓库：https://github.com/hakula139/kiln

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

- 包体积（解压后）：11.3 kB，4 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-10T18:48:49.404Z
- 最新版本发布：2026-11-01T12:50:03.650Z
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

窑炉静态现场发生器

## 安装

```sh
npm install @kiln-ssg/kiln
```

也可以使用：`pnpm add @kiln-ssg/kiln`、`yarn add @kiln-ssg/kiln`、`bun add @kiln-ssg/kiln`

## README

# 窑

[![CI](https://github.com/hakula139/kiln/actions/workflows/ci.yml/badge.svg)](https://github.com/hakula139/kiln/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/hakula139/kiln/graph/badge.svg)](https://codecov.io/gh/hakula139/kiln) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://npmcn.com/package/%40kiln-ssg/kiln/LICENSE) ![WakaTime coding time for kiln](https://wakatime.com/badge/user/f4a35a1f-0e29-4093-a647-e66aad164737/project/f00a4cb5-df90-47ef-82e5-ebc9432a2b05.svg)

一个用Rust编写的静态站点生成器 [hakula.xyz](https://hakula.xyz/)，具有cjk友好的Markdown创作和可定制的主题。

## 突出了

-   cjk友好的Markdown技术写作，与数学，图表和语法高亮显示
-   通过嵌套自定义内容组件 `:::` 指令和主题模板
-   将文字、图像和页面特定样式保持在一起的页面包
-   全文检索 [Pagefind](https://pagefind.app/)，提供查找和跟踪帖子的存档和提要
-   [IgnIt](https://github.com/hakula139/IgnIt) 主题响应式布局和黑暗模式，可通过网站覆盖自定义
-   本地预览与实时加载，加上优化的样式表和图像加载占位符发布

## 文档

| 文档 | 描述 |
| --- | --- |
| [内容](https://npmcn.com/package/%40kiln-ssg/kiln/docs/content.md) | 内容，前端内容和Hugo迁移 |
| [语法参考](https://npmcn.com/package/%40kiln-ssg/kiln/docs/syntax.md) | Markdown扩展和指令 |
| [资产和样式表](https://npmcn.com/package/%40kiln-ssg/kiln/docs/assets.md) | 发布、样式表、指纹和实时重载 |
| [主题](https://npmcn.com/package/%40kiln-ssg/kiln/docs/themes.md) | 网站配置，主题和模板 |
| [基准](https://npmcn.com/package/%40kiln-ssg/kiln/docs/benchmarks.md) | 性能测量和基线比较 |
| [路线图](https://npmcn.com/package/%40kiln-ssg/kiln/docs/roadmap.md) | 开发人员能力状态、约束和优先级 |

## 安装

### 通过npm

安装Node.js 20或更新版本，例如 [等于是](https://github.com/Schniz/fnm)，然后选择一种窑型：

```bash
fnm install --latest --use
npm install -g @kiln-ssg/kiln@latest
```

选择 `@kiln-ssg/kiln-extended@latest` 用于avf加载占位符。它有相同的 [dav1d需求](https://npmcn.com/package/%40kiln-ssg/kiln/#readme-prebuilt-binary) 作为扩展的存档。两个变体都安装 `kiln`，因此在切换之前卸载当前的变体。

预发布版本使用 `next` npm标签。支持的平台为Linux x86\_64 （glibc）、Apple Silicon和Windows x86\_64。

当站点需要时，在相同的安装命令中添加可选工具：

```bash
npm install -g @kiln-ssg/kiln@latest @kiln-ssg/tailwindcss@0.1.4 pagefind@1.5.2
```

-   `@kiln-ssg/tailwindcss`：当网站或主题编译顺风CSS时需要。
-   `pagefind`：启用搜索时必选。

### 预先构建的二进制

为您的平台下载最新版本 [释放](https://github.com/hakula139/kiln/releases/latest)：

```bash
# Linux x86_64
curl -fsSL https://github.com/hakula139/kiln/releases/latest/download/kiln-x86_64-unknown-linux-gnu.tar.gz | tar -xz
sudo mv kiln /usr/local/bin/

# macOS aarch64 (Apple Silicon)
curl -fsSL https://github.com/hakula139/kiln/releases/latest/download/kiln-aarch64-apple-darwin.tar.gz | tar -xz
sudo mv kiln /usr/local/bin/

# Windows x86_64 (Git Bash / MSYS / WSL)
curl -fsSLO https://github.com/hakula139/kiln/releases/latest/download/kiln-x86_64-pc-windows-msvc.zip
unzip kiln-x86_64-pc-windows-msvc.zip

kiln --version
```

选择默认值 `kiln-<target>` 归档文件或 `kiln-extended-<target>` 用于avf加载占位符。只有扩展的二进制文件才需要dav1d：

| 平台 | 扩展运行时需求 |
| --- | --- |
| Linux | 系统 `libdav1d` 包 |
| macOS | `brew install dav1d` |
| 窗户 | 包含在二进制文件中 |

### 从源

```bash
cargo install --git https://github.com/hakula139/kiln --locked
```

要为AVIF图像生成加载占位符，请安装 [本地依赖关系](https://npmcn.com/package/%40kiln-ssg/kiln/#readme-building-from-source) 并启用该功能：

```bash
cargo install --git https://github.com/hakula139/kiln --locked --features avif
```

### 通过无

```bash
nix run github:hakula139/kiln -- build     # one-shot
nix profile install github:hakula139/kiln  # install to user profile
```

雪花提供了 `hakula` 预构建包的缓存。Nix以交互方式提示信任。对于非交互式使用，请在传递之前验证缓存密钥 `--accept-flake-config`.

要从另一个薄片中使用此缓存，请在该薄片或您的Nix安装中配置它。

要在另一个薄片中使用窑炉，请添加以下输入：

```nix
inputs.kiln.url = "github:hakula139/kiln";
# Outputs: packages.${system}.{default,kiln}
```

Nix包将Tailwind编译器和Pagefind放在kiln的编译器上 `PATH`，因此样式表编译和搜索无需单独安装即可工作。

## 第一个网站

创建一个站点 [IgnIt](https://github.com/hakula139/IgnIt)，使用符合主题的窑版 `min_kiln_version`． 点火需要 [顺风处理器](https://npmcn.com/package/%40kiln-ssg/kiln/#readme-via-npm)，它包含在kiln的Nix包中。

```bash
git init my-site
cd my-site
git submodule add https://github.com/hakula139/IgnIt.git themes/IgnIt
mkdir -p content/posts/hello

cat > config.toml <<'CONFIG'
base_url = "https://example.com"
title = "My Site"
theme = "IgnIt"
CONFIG

cat > content/posts/hello/index.md <<'POST'
+++
title = "Hello"
+++

Welcome to my site.
POST

kiln serve --open
```

运行 `kiln build --minify` 生成 `public/` 为部署。看到 [网站配置](https://npmcn.com/package/%40kiln-ssg/kiln/docs/themes.md#site-configuration) 查看引擎设置和 [内容](https://npmcn.com/package/%40kiln-ssg/kiln/docs/content.md) 用于组织页面。

## 使用

```bash
kiln build --root /path/to/site --minify
kiln build --base-url https://preview.example.com
kiln serve --port 3000 --open
kiln init-theme my-theme
kiln convert --source /path/to/hugo --dest /path/to/kiln
```

`build`， `serve` 和 `init-theme` 使用当前目录作为站点根目录，除非 `--root` 供应。 `KILN_BASE_URL` 时提供构建URL重写 `--base-url` 不在。

看到 [雨果迁移](https://npmcn.com/package/%40kiln-ssg/kiln/docs/content.md#hugo-content-migration) 为转换器的支持范围和手动跟踪。

### 搜索

默认禁用搜索功能。要启用它，请安装 [Pagefind](https://npmcn.com/package/%40kiln-ssg/kiln/#readme-installation) 并设置 `[search] enabled = true` 在 `config.toml`：

```toml
[search]
enabled = true
# binary = "/path/to/pagefind"  # optional, if not on $PATH
```

`kiln build` 和 `kiln serve` 当启用搜索时，在生成HTML后运行Pagefind。

## 从源头构建

需要 [生锈](https://www.rust-lang.org/tools/install) 1.89或更新版本和C工具链。

```bash
cargo build --release  # Binary at target/release/kiln
```

### AVIF占位符

图像发布和尺寸检测在任何一个构建中都可以工作。要添加AVIF加载占位符，请安装dav1d≥1.3和 `pkg-config`：

| 平台 | 构建依赖关系 |
| --- | --- |
| macOS | Xcode命令行工具和 `brew install dav1d pkg-config` |
| Debian / Ubuntu | `sudo apt install build-essential libdav1d-dev pkg-config` |

然后启用该特性：

```bash
cargo build --release --features avif
```

在macOS和Linux上，生成的二进制文件在运行时需要dav1d，就像 [延长档案](https://npmcn.com/package/%40kiln-ssg/kiln/#readme-prebuilt-binary).

### 可复制的开发shell （Nix）

Nix包默认启用AVIF支持。它的开发shell提供了构建依赖和预提交钩子：

```bash
nix develop      # interactive shell
nix flake check  # run the pre-commit hooks that don't use Node
```

`direnv` 自动激活外壳通过 `.envrc`.

## 许可证

版权所有2026 [Hakula](https://hakula.xyz/)． 根据 [MIT许可证](https://npmcn.com/package/%40kiln-ssg/kiln/LICENSE).

## 常见问题

### @kiln-ssg/kiln 是什么？

窑炉静态现场发生器

### 如何安装 @kiln-ssg/kiln？

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

### @kiln-ssg/kiln 支持 TypeScript 吗？

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

### @kiln-ssg/kiln 需要什么版本的 Node\.js？

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

### @kiln-ssg/kiln 可以商用吗？

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

### @kiln-ssg/kiln 还在维护吗？

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