跳到主要内容

Docusaurus编译问题记录

· 阅读需 4 分钟

1. 编译报错​

1.1. 报错信息​

sh: 1: docusaurus: Permission denied

1.2. 解决方案​

chmod +x node_modules/.bin/docusaurus

如果仍然报 Permission denied，再检查两点：

  1. 文件系统是否被挂载成 noexec
mount | grep "$(df -P . | tail -1 | awk '{print $1}')"

看到 noexec 就重新挂载：

sudo mount -o remount,exec /mnt/disk0
  1. 确认你确实在 Linux 一侧 的 ext4 分区里运行，而不是在/mnt/disk0 这种 Windows 盘（DrvFs）上——WSL 的 DrvFs 默认带 noexec，而且 chmod 无效。 把项目 mv 到 ~/projects 之类的原生 Linux 目录再试即可。

把 NFS 挂成 noexec 是 管理员故意为之 的安全基线，不是技术做不到，而是 不允许做。原因有三条，每一条在安全合规场景里都是“硬杠杠”：

  1. 阻断远程可执行文件直接在服务器上跑 NFS 里放的文件可能是任何客户端上传的，一旦允许执行，别人只需 echo -e '#!/bin/sh\nevil' > /nfs/evil.sh; ./evil.sh 就能在服务器上拿到与挂载用户同权限的 shell。 挂成 noexec 后，即使文件有 0777 权限，内核也直接返回 EPERM， 把攻击面一刀砍掉。
  2. set-uid/set-gid 无法被客户端信任 可执行文件常常带 setuid 位来提升权限。NFS 的 uid/gid 只是 “客户端声称的数字”，服务器无法验证。 如果允许执行，客户端可以伪造 root suid 二进制，服务器一跑就提权。 noexec 让这类文件直接废掉，根本进不了内核的 execve 路径。
  3. 合规/审计要求 很多规范（SOX、ISO27001、等保 2.0）明确要求“网络文件系统不得用于存放或执行可执行代码”。 挂 noexec 是最简单、最可验证、不依赖用户自觉的技术手段， 审计员一条 mount | grep noexec 就能给通过。

2.1. 报错信息​

Possible solutions:
- Install with verbose logging and look for errors: "npm install --ignore-scripts=false --foreground-scripts --verbose sharp"
- Install for the current linux-x64 runtime: "npm install --platform=linux --arch=x64 sharp"

2.2. 解决方案​

sharp 的 原生模块 (sharp-linux-x64.node) 在 npm install 时 没有编译/下载成功，所以 build 阶段一引用就崩。 常见根因就三类：

  1. 平台不匹配 – 你在 noexec 的 NFS 上装包，post-install 脚本被禁用，sharp 没机会编译/下载预编译文件。
  2. 缺系统依赖 – libvips 或 g++ 没装，导致编译失败。
  3. CPU/架构 – 在 x64 机器上却装成了 arm64 版本（或反之）。

按顺序一次性解决：

  1. 先把 sharp 清干净（避免残留脏文件）
rm -rf node_modules/@docusaurus/responsive-loader/node_modules/sharp
  1. 装系统工具链（只缺时再装）
# Debian/Ubuntu
sudo apt update
sudo apt install -y build-essential libc6-dev libvips-dev
  1. 重新安装 sharp 并允许脚本运行
npm install --ignore-scripts=false --foreground-scripts --verbose sharp

如果你 仍在 NFS 目录 且挂载了 noexec，--ignore-scripts=false 也会失败——post-install 脚本无法执行。 要么

  • 把项目整个 cp 到本地 ext4 盘再执行， 要么
  • 临时挂成 exec 装完再挂回 noexec（运维允许的前提下）。
  1. 确认 sharp 已拿到正确二进制
ls -l node_modules/sharp/build/Release/sharp-linux-x64.node

文件存在且大小 > 1 MB 即成功。

  1. 重新 build
npm run build

一次性指令（本地磁盘场景）

# 1. 清缓存
npm cache clean --force
rm -rf node_modules package-lock.json

# 2. 全量重装（带脚本）
npm install --ignore-scripts=false

# 3. build
npm run build

做完以上，sharp 模块就能正常加载，Docusaurus 即可顺利完成生产构建。