EnglishDeploymentTroubleshooting

Troubleshooting: Deploying Nextra 3 to Cloudflare Pages

When deploying a Nextra 3 site from macOS to Cloudflare Pages (Linux), you may encounter build errors related to platform-specific binary dependencies (specifically @napi-rs/simple-git). This guide explains how to resolve them.

The Problem

Nextra uses @napi-rs/simple-git for Git features. This package relies on native binaries.

  • On your local macOS (Apple Silicon), npm installs the darwin-arm64 binary.
  • Cloudflare Pages runs on Linux x64.

If you commit your package-lock.json generated on macOS, it may lock the darwin binary. When Cloudflare tries to run npm ci (Clean Install) using this lock file, it fails because it cannot find or use the Linux binary it expects, or it strictly enforces the architecture match.

Common Error Logs

npm error code EBADPLATFORM
npm error notsup Unsupported platform for @napi-rs/simple-git-darwin-arm64
npm error notsup Actual os: linux

The Solution

The most reliable fix is to allow Cloudflare to resolve its own dependencies fresh, rather than enforcing the macOS-generated lock file.

Step 1: Remove package-lock.json from Git

Remove the lock file from your repository tracking, but keep it locally if you want (though regenerating it is safer).

git rm package-lock.json
git commit -m "Fix: Remove package-lock.json to avoid platform conflicts"
git push origin main

Step 2: Update Build Command

Change the build command in Cloudflare Pages to use npm install instead of the default npm ci (which implies a strict lock file sync).

  1. Go to Settings > Build & deployments > Edit.
  2. Change Build command to:
npm install && npm run build
  1. Save and Retry deployment.

Why this works

By running npm install without a committed lock file (or with a fresh resolution), npm on Cloudflare’s Linux server will automatically detect it is running on Linux x64 and download the correct @napi-rs/simple-git-linux-x64 binary, ignoring the macOS one completely.

Web AnalyticsOverview