> ## Documentation Index
> Fetch the complete documentation index at: https://www.bazhuayu.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装与验证

> 安装 bazhuayu-cli@0.1.32，并验证 bazhuayu 命令、Node.js 环境与本地采集运行时。

> 通过 npm 安装八爪鱼 CLI，并确认 `bazhuayu` 命令、浏览器依赖与本地运行环境可用。

八爪鱼 CLI 以 npm 包形式发布。v0.1.32 将命令入口从 `octopus` 统一为 `bazhuayu`；既有子命令、Agent 契约、任务管理、云定时和数据检查接口保持兼容。本地运行时包名仍为 `@octopus/browser-runtime`。

## 环境要求

安装前请确认：

* Node.js **20 或更高**（推荐 22 LTS）
* npm **8 或更高**
* 可用终端：PowerShell、CMD、macOS 终端或 Linux Shell
* 默认独立模式由 CLI 管理 Chrome for Testing；用户模式需要系统已安装 Chrome 或 Edge

检查版本：

```bash theme={null}
node -v
npm -v
```

## 平台支持

| 平台          | 独立浏览器本地采集 |      用户浏览器模式     | 云端采集 | 备注                                     |
| ----------- | :-------: | :--------------: | :--: | -------------------------------------- |
| Windows x64 |     支持    | 支持 Chrome / Edge |  支持  | Windows 10 / 11                        |
| macOS x64   |     支持    | 支持 Chrome / Edge |  支持  | 需 Node.js 20+                          |
| macOS arm64 |     支持    | 支持 Chrome / Edge |  支持  | 需 Node.js 20+                          |
| Linux x64   |     支持    |        不支持       |  支持  | 用户模式依赖桌面系统扩展安装能力                       |
| Linux arm64 |    暂不支持   |        不支持       |  支持  | Chrome for Testing 暂无 Linux arm64 浏览器包 |

## 安装 Node.js

### Windows

1. 访问 [Node.js 官网](https://nodejs.org/) 下载 LTS 安装包。
2. 使用默认选项安装，并确认勾选加入 `PATH`。
3. 打开 PowerShell 或 CMD，执行：

```bash theme={null}
node --version
npm --version
```

### macOS

可从 [Node.js 官网](https://nodejs.org/) 下载 macOS 安装包，或使用 Homebrew：

```bash theme={null}
brew install node
node --version
npm --version
```

### Linux / 服务器

推荐使用 [nvm](https://github.com/nvm-sh/nvm) 安装 Node.js 20+：

```bash theme={null}
node -v
npm -v
```

Linux x64 从 CLI v0.1.22 起支持本地采集；Linux arm64 目前仅建议使用云采集相关能力。

## 安装八爪鱼 CLI

安装或更新到 v0.1.32：

```bash theme={null}
npm install -g bazhuayu-cli@0.1.32
```

安装完成后，命令名为：

```bash theme={null}
bazhuayu
```

查看版本与帮助：

```bash theme={null}
bazhuayu --version
bazhuayu --help
```

v0.1.32 应能看到 `browser`、`detect`、`task-group`、`template`、`schedule` 和 `data preview` 等命令：

```bash theme={null}
bazhuayu browser --help
bazhuayu detect --help
bazhuayu task-group --help
bazhuayu data preview --help
```

## 从 `octopus` 迁移

v0.1.32 已删除 `octopus` 可执行命令。请将脚本、CI、Agent 配置和日常终端命令中的 `octopus` 全部替换为 `bazhuayu`；子命令和参数不变。

```bash theme={null}
# 旧：octopus detect URL --auto
bazhuayu detect URL --auto
```

环境变量 `OCTOPUS_API_KEY`、`OCTOPUS_ACCESS_TOKEN`、`OCTOPUS_API_BASE_URL` 及配置目录 `~/.octopus` 仍保持原名。过渡期间可在 PowerShell 当前会话中使用：

```powershell theme={null}
Set-Alias -Name octopus -Value bazhuayu
```

## 运行环境诊断

```bash theme={null}
bazhuayu doctor
bazhuayu browser status --browser-id chrome --json
```

`doctor` 会检查 Node.js、本地运行时、Chrome for Testing 和认证/API 环境，并在 Windows / macOS 上报告可选用户浏览器的扩展状态。`browser status --json` 用于检查 Chrome / Edge、Profile 与扩展是否达到 `readyForUserBrowserRun: true`。

## 更新与卸载

更新到指定版本：

```bash theme={null}
npm install -g bazhuayu-cli@0.1.32
bazhuayu --version
```

卸载：

```bash theme={null}
npm uninstall -g bazhuayu-cli
```

## 常见问题

| 现象                                 | 处理建议                                                                             |
| ---------------------------------- | -------------------------------------------------------------------------------- |
| `bazhuayu: command not found`      | 将 Node.js 目录和 npm 全局 bin 目录加入系统 `PATH`                                           |
| 升级后 `octopus` 命令找不到                | v0.1.32 已改名为 `bazhuayu`；更新脚本和 Agent 调用，不要改 `OCTOPUS_*` 环境变量                      |
| PowerShell 中文参数被拆开                 | 给中文参数加双引号，例如 `--goal "提取电影名称、评分"`                                                |
| PowerShell 多行命令报错                  | 使用反引号 `` ` `` 续行，或优先写成单行                                                         |
| URL 无法打开                           | 检查是否写完整协议，例如 `https://example.com`                                               |
| `--output task.json` 写到意外目录        | 先 `cd` 到工作目录，或使用绝对路径                                                             |
| `npm install -g ...@latest` 卡住或被终止 | 使用固定版本：`npm install -g bazhuayu-cli@0.1.32`                                      |
| `doctor` 某项失败                      | 根据 `ok: false` 的检查项修复 Node.js、本地运行时或浏览器依赖                                        |
| 用户浏览器扩展未就绪                         | 按 [`browser` 首次配置流程](/docs/zh/cli/core-commands/browser-management) 安装扩展、重开浏览器并再次检查状态 |

## 下一步

<CardGroup cols={2}>
  <Card title="获取 API Key 并登录" href="/docs/zh/cli/quick-start/get-api-key-and-log-in">
    创建 Key，或使用 OAuth / 环境变量完成 CLI 认证。
  </Card>

  <Card title="运行第一个任务" href="/docs/zh/cli/quick-start/run-your-first-task">
    从新 URL 生成任务并运行，或运行已有任务并导出数据。
  </Card>

  <Card title="浏览器管理" href="/docs/zh/cli/core-commands/browser-management">
    配置 Chrome / Edge 用户 Profile 和登录状态复用。
  </Card>
</CardGroup>