# 安装与运行

URL: https://caijiao.org/pagefind/tutorial-02-installation
Source: docs/pagefind/tutorial-02-installation.md
Description: 讲解如何通过 npx、pnpm、Python 包或二进制文件运行 Pagefind，并把它接入静态站点构建流程。

Pagefind 支持 Windows、macOS 和 Linux。对于 Node.js 项目，最常见的方式是通过 npm 包运行。

## 使用 npx 快速运行

假设静态站点已经输出到 `public/`：

```bash
npx -y pagefind --site public --serve
```

其中：

- `--site public` 指向已经构建好的静态站点目录。
- `--serve` 会在生成索引后启动本地预览，方便验证搜索效果。

正式部署时通常去掉 `--serve`：

```bash
npx -y pagefind --site public
```

## 在项目中固定版本

生产项目建议把 Pagefind 放入依赖，让 CI 和本地构建使用同一版本：

```bash
pnpm add -D pagefind
```

然后在构建脚本里追加索引步骤：

```json
{
  "scripts": {
    "build": "vite build && pagefind --site dist"
  }
}
```

如果使用 pnpm，也可以显式通过 `pnpm exec` 调用：

```bash
pnpm exec pagefind --site dist --output-path dist/_pagefind
```

## Python 与二进制方式

Python 项目可以安装扩展版本：

```bash
python3 -m pip install 'pagefind[extended]'
python3 -m pagefind --site public
```

也可以从 GitHub Release 下载预编译二进制文件：

```bash
./pagefind --site public
./pagefind_extended --site public
```

扩展版本包含对中文、日文等特殊语言的更好分词支持。面向中文站点时，优先使用 npm 包、`pagefind[extended]` 或 `pagefind_extended`。

## 构建顺序

Pagefind 必须在静态页面生成之后运行：

```text
1. 生成 HTML
2. 复制静态资源
3. 运行 pagefind
4. 部署最终输出目录
```

如果在开发服务器启动时直接访问源码页面，通常看不到搜索结果，因为 Pagefind 还没有扫描最终 HTML。