Docs: improve cross-platform help messaging

tldr; don't use npm for multi-platform installs

.github/ISSUE_TEMPLATE/installation.md

@@ -11,7 +11,10 @@ labels: installation
 
 <!-- Please place an [x] in the box to confirm. -->
 
-- [ ] I have read the [documentation relating to installation](https://sharp.pixelplumbing.com/install).
+- [ ] I have read and understood all of the [documentation relating to installation](https://sharp.pixelplumbing.com/install).
+- [ ] I have searched for known bugs relating to this problem in my choice of package manager.
+
+You must confirm both of these before continuing.
 
 ### Are you using the latest version of sharp?
 
@@ -47,7 +50,7 @@ and try again before opening an issue.
 
 If you cannot confirm any of these,
 please upgrade to the latest version of your chosen package manager
-and ensure you are allowing the installation of optional dependencies
+and ensure you are allowing the installation of optional or multi-platform dependencies
 before opening an issue.
 
 ### What is the complete output of running `npm install --verbose --foreground-scripts sharp` in an empty directory?

docs/install.md

@@ -4,6 +4,10 @@ Works with your choice of JavaScript package manager.
 
 > ⚠️  **Please ensure your package manager is configured to install optional dependencies**
 
+If a package manager lockfile must support multiple platforms,
+please see the [cross-platform](#cross-platform) section
+to help decide which package manager is appropriate.
+
 ```sh
 npm install sharp
 ```
@@ -51,17 +55,21 @@ JPEG, PNG, WebP, AVIF (limited to 8-bit depth), TIFF, GIF and SVG (input) image
 
 ## Cross-platform
 
-At install time, package managers will automatically select prebuilt binaries for the current OS platform and CPU architecture, where available.
+At install time, package managers will automatically select prebuilt binaries
+for the current OS platform and CPU architecture, where available.
 
-Some package managers support multiple platforms and architectures within the same installation tree.
+Some package managers support multiple platforms and architectures
+within the same installation tree and/or using the same lockfile.
 
 ### npm
 
-Use the `--os`, `--cpu` and `--libc` flags:
+> ⚠️ **npm `package-lock.json` files can cause installation problems due to [npm bug #4828](https://github.com/npm/cli/issues/4828)**
+
+Provides limited support via `--os`, `--cpu` and `--libc` flags.
 
 Example to support both Intel and ARM CPUs on macOS:
 ```sh
-npm install --cpu=x64 --os=darwin  sharp
+npm install --cpu=x64 --os=darwin sharp
 npm install --cpu=arm64 --os=darwin sharp
 ```
 

lib/sharp.js

@@ -49,19 +49,18 @@ if (sharp) {
     help.push(
       '- Ensure optional dependencies can be installed:',
       '    npm install --include=optional sharp',
-      '  or',
       '    yarn add sharp --ignore-engines',
+      '- Ensure your package manager supports multi-platform installation:',
+      '    See https://sharp.pixelplumbing.com/install#cross-platform',
       '- Add platform-specific dependencies:',
       `    npm install --os=${os} --cpu=${cpu} sharp`,
-      '  or',
       `    npm install --force @img/sharp-${runtimePlatform}`
     );
   } else {
     help.push(
       `- Manually install libvips >= ${minimumLibvipsVersion}`,
       '- Add experimental WebAssembly-based dependencies:',
       '    npm install --cpu=wasm32 sharp',
-      '  or',
       '    npm install --force @img/sharp-wasm32'
     );
   }
@@ -103,7 +102,7 @@ if (sharp) {
   }
   help.push(
     '- Consult the installation documentation:',
-    '    https://sharp.pixelplumbing.com/install'
+    '    See https://sharp.pixelplumbing.com/install'
   );
   throw new Error(help.join('\n'));
 }