工程环境
本地工具链与构建验证
Node、pnpm、Astro 检查、静态构建和 Pagefind 索引的本地命令与已知注意事项。
本文目录
本站使用 Node.js + pnpm + Astro 的静态构建链路，不依赖数据库或后端服务。
环境
- Node.js
>=22.23.4（Astro 7 的 engines 要求）； - pnpm 12.x；
- Git；
- 可选：任意静态文件服务器或
astro preview。
首次安装：
pnpm install常用命令
| 命令 | 作用 |
|---|---|
pnpm dev |
启动开发服务器，包含草稿 |
pnpm check |
运行 Astro 与 TypeScript 诊断 |
pnpm build:site |
只生成静态 HTML |
pnpm build |
构建 HTML 并生成 Pagefind 索引 |
pnpm preview |
预览 dist/ |
pnpm search:index |
单独重建搜索索引 |
构建顺序
pnpm build 先执行 astro build，再执行 pagefind --site dist。Pagefind 读取已生成的 HTML，因此正文必须在静态 HTML 中；如果正文依赖客户端渲染，搜索索引会缺失内容。
已知注意事项
@astrojs/check 的依赖链中曾出现 @napi-rs/wasm-runtime 的 peer 依赖版本不匹配，导致在 Node.js 25 下加载 WASM 模块时报 this.bridge.deleteEnv is not a function。项目通过显式固定 @emnapi/runtime@1.11.3 解决；这不是 Astro 的通用配置，升级依赖后应重新运行 pnpm check 确认。
当前 pnpm check、pnpm build 已通过；Pagefind 1.6.0 Extended 已在本机 Chromium 中用“架构”“输入法”“WSLg”等关键词验证，具体结果与限制见项目 README。站点已部署到 https://nekotail.moe，但 CDN/WAF 对爬虫的拦截、缓存命中与搜索引擎收录仍未在本项目内验证。