EdgeOne Pages 构建环境的 Pagefind 二进制踩坑

问题描述

wyclab.com（基于 Astro）使用 Pagefind 做内容搜索，构建时报错：

pagefind: not found
or
/lib/ld-musl-x86_64.so.1: No such file or directory

根因分析

EdgeOne Pages 构建环境是 Alpine Linux + musl libc，而 pagefind 的 npm 包内含一个预编译的 x86_64 glibc 二进制，musl 环境下无法运行。

更糟糕的是：

1. 构建报错时 EdgeOne 仍然会静默部署——所以你看到的"成功"其实是 deploy 状态码 200，但产物里 public/pagefind/ 是空的或残缺的
2. Astro 的 output: 'static' + npx pagefind --site dist 通常会自动在 post-build 运行，失败也只 warn 不 fail

解决方案：本地预生成 pagefind 索引

把 pagefind 的产物（public/pagefind/ 目录）直接提交到 Git 仓库，EdgeOne 构建时不再运行 pagefind 二进制：

步骤

# 本地（macOS / glibc 环境）
npm install
npm run build
npx pagefind --site dist
git add public/pagefind/
git commit -m "chore: 提交预生成的 pagefind 索引"
git push

# EdgeOne Pages 部署
# bun install → bun run build → 自动部署 dist/client
# pagefind 索引已经随仓库一起推上去了，无需在 EdgeOne 上重新生成

注意事项

• public/pagefind/ 文件夹比较大（10MB+），建议用 Git LFS 或接受直接提交
• 每次文章更新后都要本地重新生成 + 提交
• EdgeOne 构建的 bun install 会执行 optionalDependencies，如果失败需要显式加 --no-optional 或者用纯 JS 的 pagefind 实现

另一种完全规避的方案：换 VitePress

VitePress 内置的本地搜索基于 MiniSearch，纯 JS，零二进制。构建时只生成一个 assets/search-index.json，不依赖任何外部工具。

详见新仓库 wyclab/vitepress-blog。

总结

• EdgeOne Pages = musl/Alpine，二进制工具链有兼容性问题
• 构建报错 ≠ 部署失败，必须手动验证产物完整性
• 静态产物的二进制依赖尽量放到本地预生成，CI/构建只做最朴素的拷贝