Translated by AI model deepseek-flash.
Source Language: Simplified Chinese, Target Language: english, Translation Time: 2026-10-27 10:20
.AI translation is for reference only. Accuracy is not guaranteed, please refer to the original text.
Foreword
This article documents the actual steps taken to fix pnpm build errors and achieve a complete build for an Astro 7 project on Termux / Android.
The Astro 7 project itself uses unified() from @astrojs/markdown-remark as its Markdown processor, but its configuration schema imports @astrojs/markdown-satteri during the module loading stage. Sätteri has no Android native binding, so even though the project uses unified(), it still triggers loading of Sätteri's native binding.
Test Environment
| Component | Version |
|---|---|
| Android | 14 / aarch64 |
| Node.js | 25.8.1 |
| pnpm | 11.0.9 |
| Astro | 7.4.2 |
| Pagefind | 1.5.2 |
| Sätteri | 0.10.5 |
1. Sätteri Has No Android Native Binding
Symptom
Cannot find native binding. npm has a bug related to optional dependencies...
cause: Error: Cannot find module '@bruits/satteri-android-arm64'
astro check fails at the configuration loading stage, before content processing even begins.
Diagnosis
@astrojs/markdown-satteri depends on satteri. The optionalDependencies of satteri@0.10.5 are only:
@bruits/satteri-linux-x64-gnu
@bruits/satteri-linux-arm64-gnu
@bruits/satteri-linux-x64-musl
@bruits/satteri-linux-arm64-musl
@bruits/satteri-darwin-x64
@bruits/satteri-darwin-arm64
@bruits/satteri-win32-x64-msvc
@bruits/satteri-win32-arm64-msvc
@bruits/satteri-wasm32-wasi
There is no android-arm64 among them. However, satteri's binding loader includes an Android branch and a WASI fallback:
if (process.platform === 'android') {
if (process.arch === 'arm64') {
try { return require('./satteri_napi.android-arm64.node') } catch (e) { ... }
}
}
...
if (!nativeBinding || forceWasi) {
try {
wasiBinding = require('@bruits/satteri-wasm32-wasi')
nativeBinding = wasiBinding
} catch (err) { ... }
}
Therefore, using the WASI package directly is sufficient; there is no need to compile an Android native module.
Fix
Install the WASI fallback:
pnpm add -D @bruits/satteri-wasm32-wasi@0.10.5
After installation, satteri can find the WASI binding, but reports a second error:
Error: UVWASI_EACCES, uvwasi_init
The cause is that WASI initialization uses / as the preopen:
const __rootDir = __nodePath.parse(process.cwd()).root
const __wasi = new __nodeWASI({
version: 'preview1',
env: process.env,
preopens: {
[__rootDir]: __rootDir,
}
})
Android does not allow preopening the root directory, so change it to process.cwd():
pnpm patch @bruits/satteri-wasm32-wasi@0.10.5
Edit the temporary directory output by pnpm:
node_modules/.pnpm_patches/@bruits/satteri-wasm32-wasi@0.10.5/satteri_napi.wasi.cjs
-const __rootDir = __nodePath.parse(process.cwd()).root
+const __rootDir = process.cwd()
node_modules/.pnpm_patches/@bruits/satteri-wasm32-wasi@0.10.5/wasi-worker.mjs
-const __rootDir = parse(process.cwd()).root;
+const __rootDir = process.cwd();
Commit the patch:
pnpm patch-commit node_modules/.pnpm_patches/@bruits/satteri-wasm32-wasi@0.10.5
The following is ultimately generated in the repository:
patches/@bruits__satteri-wasm32-wasi@0.10.5.patch
Notes
pnpm patch-commit sometimes displays Already up to date, but the files in the installed node_modules are still the old ones. Do not try to solve this with pnpm install --force; just delete and reinstall:
rm -rf node_modules
pnpm install --frozen-lockfile
Verify that Sätteri can load:
node -e "
const { createRequire } = require('module');
const r = createRequire(process.cwd() + '/node_modules/.pnpm/satteri@0.10.5/node_modules/satteri/index.js');
const m = r('satteri');
console.log('satteri OK', Object.keys(m).length);
"
It outputs satteri OK 34, accompanied by an ExperimentalWarning: WASI is an experimental feature, which is normal.
2. Pagefind Lacks an Android Build (If Pagefind Is Used)
Symptom
astro build has already completed, but the postbuild stage fails:
$ pagefind --site dist
Failed to install either of [pagefind_extended, pagefind].
Most likely the platform android-arm64 is not yet a supported architecture.
Diagnosis
pagefind/lib/resolveBinary.js directly concatenates the package name based on process.platform:
const cpu = process.env.npm_config_arch || os.arch();
const platform = process.platform === "win32" ? "windows" : process.platform;
for (const execname of execnames) {
const executable = platform === "windows" ? `${execname}.exe` : execname;
try {
return require.resolve(`@pagefind/${platform}-${cpu}/bin/${executable}`);
} catch (e) {}
}
There is no @pagefind/android-arm64.
However, the pagefind_extended in @pagefind/linux-arm64 is an aarch64 binary statically linked against musl:
ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV),
statically linked, stripped
It can be executed directly on Termux, without proot / glibc-runner. Tested:
./package/bin/pagefind_extended --version
# pagefind 1.5.2
./package/bin/pagefind_extended --site dist
# Indexed 21 pages
Therefore, only two things need to be solved:
- Make pnpm install
@pagefind/linux-arm64on Android; - Make the Pagefind wrapper look for
linux-arm64on Android instead ofandroid-arm64.
Fix A: Make pnpm Install the linux-arm64 Optional Package
Add the following to pnpm-workspace.yaml:
supportedArchitectures:
os:
- current
- linux
cpu:
- current
libc:
- current
This way, pnpm will also link in optional packages with os: ["linux"] and cpu: ["arm64"]. On Android arm64, the following will be installed:
node_modules/.pnpm/@pagefind+linux-arm64@1.5.2/
Side effect: pnpm 11.0.9 will also install the linux-arm64 gnu/musl variants of other packages (sharp, rolldown, biome, lightningcss, oxc, etc.), making node_modules about 680MB. This is an installation size issue and does not affect the packages actually loaded on Android.
Fix B: Make Pagefind Recognize Android
pnpm patch pagefind@1.5.2
Edit node_modules/.pnpm_patches/pagefind@1.5.2/lib/resolveBinary.js:
-const platform = process.platform === "win32" ? "windows" : process.platform;
+const platform =
+ process.platform === "win32"
+ ? "windows"
+ : process.platform === "android"
+ ? "linux"
+ : process.platform;
Commit:
pnpm patch-commit node_modules/.pnpm_patches/pagefind@1.5.2
Generate:
patches/pagefind@1.5.2.patch
This mapping does not change behavior on non-Android platforms.
Notes
Likewise, do not use pnpm install --force. Previously tested, it installs the optionalDependencies of all platforms (Windows, macOS, Linux x64/mips, etc.), directly filling up the disk.
When the patch does not take effect:
rm -rf node_modules
pnpm install --frozen-lockfile
Verify:
./node_modules/.bin/pagefind --version
# pagefind 1.5.2
./node_modules/.bin/pagefind --site dist
# Indexed 21 pages
3. Final Verification
pnpm build
Actual results:
astro check: 0 errors / 0 warnings
astro build: 48 page(s) built
pagefind: Indexed 21 pages
pnpm test
Actual results:
tests 13
pass 13
fail 0
build assertions passed: 21 indexed pages, 20 default RSS items
pnpm lint
# Checked 79 files. No fixes applied.
Both pnpm dev --host 127.0.0.1 and pnpm preview --host 127.0.0.1 return HTTP 200. Astro 7's dev/preview run in the background; to stop them:
pnpm exec astro dev stop
pnpm exec astro preview stop
If you enjoyed this, leave a comment~