|
|
@@ -0,0 +1,111 @@
|
|
|
+# Linux / Windows 构建说明
|
|
|
+
|
|
|
+在出现 `npm ERR! cb() never called!` 或大量 deprecated 警告后安装失败时，按下面顺序尝试。
|
|
|
+
|
|
|
+**验证说明**：在本机（Node 14 + npm 6、Windows）实测，直接 `npm install` 会在若干 deprecated 警告后报 `cb() never called!` 并退出；使用 **`npm install --ignore-scripts`** 后，安装能越过该处并正常进行（仅出现相同警告，无上述错误）。建议优先使用下方「1. 跳过脚本安装」流程。
|
|
|
+
|
|
|
+**完整验证结果**（同环境）：
|
|
|
+- `npm cache clean --force` + `npm cache verify` + 删除 `node_modules` + **`npm install --ignore-scripts`** → **成功**（约 14 分钟，3313 个包，无 cb 错误）。
|
|
|
+- `npm rebuild node-sass` → 本机因镜像 404 与 Python/node-gyp 环境未通过，属环境问题；若你处镜像或编译环境正常，该步可成功。
|
|
|
+- `npm run build` 依赖 node-sass 的 binding，在 binding 缺失时会报 `Missing binding ... node-sass\vendor\...\binding.node`；在 **安装 + node-sass 可用** 后，构建即可通过。
|
|
|
+
|
|
|
+## 1. 跳过脚本安装（优先尝试）
|
|
|
+
|
|
|
+很多情况下是某个依赖的 **postinstall 脚本** 未正确结束导致该错误。先跳过所有生命周期脚本安装，再单独编译原生模块：
|
|
|
+
|
|
|
+```bash
|
|
|
+npm cache clean --force
|
|
|
+npm cache verify
|
|
|
+rm -rf node_modules
|
|
|
+npm install --ignore-scripts
|
|
|
+npm rebuild node-sass
|
|
|
+```
|
|
|
+
|
|
|
+若上述能成功，后续可直接用 `npm install`（或继续用 `npm install --ignore-scripts` 再 `npm rebuild node-sass`）。
|
|
|
+
|
|
|
+### node-sass 重建失败（404 / Python 报错）
|
|
|
+
|
|
|
+- **镜像 404**：项目 `.npmrc` 已改为 **npmmirror**（`sass_binary_site=https://npmmirror.com/mirrors/node-sass/`），请先直接再执行一次 `npm rebuild node-sass`。若仍 404，可改为从 GitHub 下载二进制后再重建：
|
|
|
+ - **Windows PowerShell**：
|
|
|
+ ```powershell
|
|
|
+ $env:SASS_BINARY_SITE="https://github.com/sass/node-sass/releases/download/v4.14.1"
|
|
|
+ npm rebuild node-sass
|
|
|
+ ```
|
|
|
+ - **Linux / macOS**：
|
|
|
+ ```bash
|
|
|
+ export SASS_BINARY_SITE="https://github.com/sass/node-sass/releases/download/v4.14.1"
|
|
|
+ npm rebuild node-sass
|
|
|
+ ```
|
|
|
+- **Python SyntaxError（Missing parentheses in call to 'print'）**：说明下载二进制失败后走了本地编译，而当前是 **Python 3**，旧版 node-gyp 需要 **Python 2.7**。优先按上面设置 `SASS_BINARY_SITE` 用二进制，避免本地编译；若必须本地编译，可安装 Python 2.7 并让 `python` 指向 2.7，或使用 [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) 等。
|
|
|
+
|
|
|
+## 2. 升级 npm 后使用 overrides（推荐）
|
|
|
+
|
|
|
+本项目已在 `package.json` 中加入了 `overrides`，用于替换易出问题的传递依赖（如旧版 browserslist、circular-json）。**需 npm 8.3+ 才会生效**。Node 14 自带 npm 6，需先升级：
|
|
|
+
|
|
|
+```bash
|
|
|
+npm install -g npm@8
|
|
|
+```
|
|
|
+
|
|
|
+然后清理并重新安装：
|
|
|
+
|
|
|
+```bash
|
|
|
+npm cache clean --force
|
|
|
+npm cache verify
|
|
|
+rm -rf node_modules
|
|
|
+npm install
|
|
|
+```
|
|
|
+
|
|
|
+## 3. 仅清理缓存后重装
|
|
|
+
|
|
|
+```bash
|
|
|
+npm cache clean --force
|
|
|
+npm cache verify
|
|
|
+rm -rf node_modules
|
|
|
+npm install
|
|
|
+```
|
|
|
+
|
|
|
+## 4. 使用推荐 Node / npm 版本
|
|
|
+
|
|
|
+本项目为 Vue 2 + Webpack 3 技术栈，建议使用：
|
|
|
+
|
|
|
+- **Node**: 14.x 或 16.x LTS（避免 Node 18+ 与部分旧依赖不兼容）
|
|
|
+- **npm**: 6.x 或 7.x
|
|
|
+
|
|
|
+```bash
|
|
|
+node -v # 建议 v14.x 或 v16.x
|
|
|
+npm -v # 建议 6.x 或 7.x
|
|
|
+```
|
|
|
+
|
|
|
+若使用 Node 18+，可先升级 npm 再试：
|
|
|
+
|
|
|
+```bash
|
|
|
+npm install -g npm@latest
|
|
|
+```
|
|
|
+
|
|
|
+## 5. 仍失败时可尝试
|
|
|
+
|
|
|
+- **不使用 lock 安装**（适用于当前仓库未提交 package-lock.json 时）：
|
|
|
+ ```bash
|
|
|
+ npm install --no-package-lock
|
|
|
+ ```
|
|
|
+- **跳过可选依赖**（减少 node-sass 等原生模块导致的异常）：
|
|
|
+ ```bash
|
|
|
+ npm install --no-optional
|
|
|
+ ```
|
|
|
+- **使用国内镜像**（若 .npmrc 中 Taobao 镜像在 Linux 下异常，可临时改用 npmmirror）：
|
|
|
+ ```bash
|
|
|
+ npm config set registry https://registry.npmmirror.com
|
|
|
+ ```
|
|
|
+
|
|
|
+## 6. 关于 deprecated 警告
|
|
|
+
|
|
|
+- `browserslist@1.7.7`、`circular-json@0.3.3` 等警告来自依赖的依赖，一般不影响安装。
|
|
|
+- `package.json` 中已配置 `overrides`，在 npm 8.3+ 下会替换为较新版本，可减少此类警告与潜在错误。
|
|
|
+
|
|
|
+## 7. 构建命令
|
|
|
+
|
|
|
+安装成功后，构建命令与 Windows 一致：
|
|
|
+
|
|
|
+```bash
|
|
|
+npm run build
|
|
|
+```
|
