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 脚本 未正确结束导致该错误。先跳过所有生命周期脚本安装，再单独编译原生模块：

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：
```
$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 等。

2. 升级 npm 后使用 overrides（推荐）

本项目已在 package.json 中加入了 overrides，用于替换易出问题的传递依赖（如旧版 browserslist、circular-json）。需 npm 8.3+ 才会生效。Node 14 自带 npm 6，需先升级：

npm install -g npm@8

然后清理并重新安装：

npm cache clean --force
npm cache verify
rm -rf node_modules
npm install

3. 仅清理缓存后重装

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

node -v   # 建议 v14.x 或 v16.x
npm -v    # 建议 6.x 或 7.x

若使用 Node 18+，可先升级 npm 再试：

npm install -g npm@latest

5. 仍失败时可尝试

不使用 lock 安装（适用于当前仓库未提交 package-lock.json 时）：
```
npm install --no-package-lock
```
- 跳过可选依赖（减少 node-sass 等原生模块导致的异常）： bash npm install --no-optional
使用国内镜像（若 .npmrc 中 Taobao 镜像在 Linux 下异常，可临时改用 npmmirror）：
```
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 一致：
```
npm run build
```

BUILD-LINUX.md 4.3 KB Histórico Raw