# 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
```