# 安装与版本

npm 软件包、平台二进制、更新和从 Zig 源码构建。

版本、变更与要求见 [Framework 3.2 与 CLI 1.0](/zh-cn/docs/guides/releases/)。


<span id="usar-la-distribución-npm"></span>

<span class="section-anchor" id="section-1"></span>

## 使用 npm 分发版本

```bash
npm install -g @wu-framework/cli@1.2.0
wu --version
wu --help
```

软件包通过 `bin/wu.js` 提供 `wu` 命令，并声明 Node `>=20`。安装时启动器不编译 Zig，而是查找平台对应的预打包二进制。应用依赖随后在项目内通过 `wu install` 安装。

临时调用软件包时，可使用 npm 执行器：

```bash
npx @wu-framework/cli@1.2.0 --version
```

此调用仍需要 Node/npm 环境，也可能查询注册表，不等同于直接运行二进制文件。

<span id="plataformas-seleccionadas-por-el-launcher"></span>

<span class="section-anchor" id="section-2"></span>

## 启动器选择的平台

| Node 平台 | 架构 | `bin/` 中预期的文件 |
| --- | --- | --- |
| `win32` | `x64` | `wu-win32-x64.exe` |
| `linux` | `x64` | `wu-linux-x64` |
| `linux` | `arm64` | `wu-linux-arm64` |
| `darwin` | `x64` | `wu-darwin-x64` |
| `darwin` | `arm64` | `wu-darwin-arm64` |

该版本发布六个包：启动器和五个可选的 `@wu-framework/cli-<os>-<cpu>` 包，均精确固定为 `1.2.0`。npm 选择平台；Windows ARM64 使用 x64 二进制文件。启动器根据 `bin/SHA256SUMS` 验证版本和 SHA-256。此版本还在根包中保留全部五个二进制文件作为回退。

在 Unix 上，系统以 `EACCES` 拒绝二进制时，启动器会尝试修正执行权限，并重试一次。在 Windows 上，内部 npm 调用通过系统解释器运行 `npm.cmd`。

Linux 二进制文件使用静态 musl 构建，也可在 Alpine 上运行。发布使用 ReleaseSafe 和精确的 Zig `0.16.0`。若缺失可选包，使用 `npm install -g @wu-framework/cli@1.2.0 --include=optional` 重新安装；`wu update` 已添加此选项。不支持的平台组合、错误的包版本或校验和不匹配会报告诊断并以 `1` 退出。

<span id="actualizar"></span>

<span class="section-anchor" id="section-3"></span>

## 更新

```bash
wu update
```

启动器查询 `@wu-framework/cli@latest`，验证返回的版本并按 SemVer 比较。存在更高版本时，全局安装该精确版本。无法查询 npm 或安装失败时返回 1，不更改项目中的框架依赖。

被动更新提示使用 24 小时缓存，失败查询也会缓存。`wu update` 不等待缓存，直接重新查询。`WU_DISABLE_UPDATE_CHECK=1` 或带有 `CI` 的环境会跳过被动提示，但不会禁用显式请求的更新。

```powershell
$env:WU_DISABLE_UPDATE_CHECK = '1'
wu --version
```

直接执行 `wu.exe update` 会提示更新由启动器负责，并以 1 结束。请使用 npm 安装的命令更新。

更新 CLI 不会更改项目：接着执行 `wu upgrade --dry-run`，检查 Framework 4 迁移，使用 `wu upgrade --yes` 应用并执行 `wu install`。[依赖与迁移](/zh-cn/docs/cli/dependencies/)说明固定版本、备份、codemod 和 CI 退出码。

<span id="construir-desde-el-código"></span>

<span class="section-anchor" id="section-4"></span>

## 从源码构建

`build.zig.zon` 要求最低 Zig **0.16.0**。Zig 包不声明外部依赖，构建出的可执行文件链接 libc。

```bash
zig build -Doptimize=ReleaseSafe
zig build test --summary all
zig build run -- --version
npm test
```

`run` 步骤会转发 `--` 后的参数。`npm test` 验证不变量及启动器和编译器的 Node 测试，与 Zig 测试块属于不同套件。编译不能替代生成应用的浏览器测试。

维护者流程：`npm run build:binaries` 生成五个平台及其校验和。`node scripts/publish.mjs` 执行检查并模拟发布全部六个包；只有 `--yes` 才实际发布。它要求干净的工作树、一致的版本和有效二进制文件，并先发布平台包再发布启动器。直接执行 `npm publish` 会被拒绝。此流程用于分发 CLI，不用于部署应用。

<span id="diagnóstico-de-instalación"></span>

<span class="section-anchor" id="section-5"></span>

## 安装诊断

| 现象 | 检查 |
| --- | --- |
| 无法识别 `wu` | 检查 npm 安装，并确认可执行文件目录位于 PATH |
| `no usable executable` | 检查打包二进制，或使用 Zig 构建源码 checkout |
| 版本不符合预期 | 运行 `wu --version`，确认 shell 实际解析到的可执行文件 |
| 缺少 Vue/Svelte 编译器 | 在项目内运行 `wu install` 并检查微应用依赖 |
| 更新无法访问注册表 | 检查网络和 npm 配置；被动提示不会阻止请求的命令 |

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-6"></span>

## 实现参考

- `wu-cli/package.json`
- `wu-cli/bin/wu.js`
- `wu-cli/scripts/build-all.mjs`
- `wu-cli/scripts/publish.mjs`
- `wu-cli/scripts/test-package.mjs`
- `wu-cli/tests/bin-wu.test.cjs`