> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 start 命令完成构建 + 启动流程

> 一条命令跑完生产构建并立刻在浏览器中启动扩展。把 build 与 preview 合成一步。

当你想用一条命令完成生产构建并立刻启动浏览器时，使用 `start`。

`start` 命令先跑生产构建，再用与 `preview` 相同的流程启动构建好的扩展。

## 什么时候使用 `start`

* 编译完成后立刻手动验证生产行为。
* 复现 watch 模式与生产输出之间的运行时差异。
* 在本地跑一次类生产检查，而不需要分别跑 `build` 再跑 `preview`。

## start 命令的能力

| 能力         | 你得到什么                    |
| ---------- | ------------------------ |
| 构建 + 启动工作流 | 一步完成生产编译与浏览器启动           |
| 目标选择       | 直接在所选浏览器或引擎目标上启动         |
| runner 控制  | 只需要构建验证时可以跳过浏览器启动        |
| 类生产验证      | 检查真实的编译输出，而不是 watch 模式状态 |

## 与其他命令的区别

* `dev`：dev 服务器 + 热模块替换（HMR）/ watch 模式
* `build`：仅生产构建
* `preview`：不构建、直接启动已构建好的扩展
* `start`：依次执行 `build` + `preview`

## 用法

<CodeGroup>
  ```bash npm theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash pnpm theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash yarn theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash bun theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash bun theme={null}
  extension start [path-or-url] [options]
  ```
</CodeGroup>

如果省略路径，命令会使用当前工作目录。

## 参数与 flag

| flag                           | 别名                 | 作用                                                     | 默认值             |
| ------------------------------ | ------------------ | ------------------------------------------------------ | --------------- |
| `[path or url]`                | -                  | 扩展路径或远程 URL。                                           | `process.cwd()` |
| `--browser <browser>`          | -                  | 浏览器 / 引擎目标。                                            | `chromium`      |
| `--profile <path\|boolean>`    | -                  | 浏览器 profile 路径或布尔的 profile 模式。                         | 全新 profile      |
| `--chromium-binary <path>`     | -                  | 自定义的 Chromium 家族二进制路径。                                 | 系统默认            |
| `--gecko-binary <path>`        | `--firefox-binary` | 自定义的 Gecko 家族二进制路径。                                    | 系统默认            |
| `--polyfill [boolean]`         | -                  | 为 Chromium 目标启用 `browser.*` API 兼容 polyfill。           | `true`          |
| `--starting-url <url>`         | -                  | 启动浏览器时的起始 URL。                                         | 未设置             |
| `--no-browser`                 | -                  | 构建但跳过浏览器启动。                                            | 默认启用浏览器启动       |
| `--wait [boolean]`             | -                  | 等待 `dist/extension-js/<browser>/ready.json` 并退出。       | 关闭              |
| `--wait-timeout <ms>`          | -                  | `--wait` 模式的超时时间。                                      | `60000`         |
| `--wait-format <pretty\|json>` | -                  | 等待结果的输出格式（`json` 适合机器读取）。                              | `pretty`        |
| `--port <port>`                | -                  | 启用 runner 时使用的 runner / devtools 端口。用 `0` 让 OS 自动分配端口。 | `8080`          |
| `--host <host>`                | -                  | 绑定 dev 服务器的主机。Docker / dev container 中可用 `0.0.0.0`。    | `127.0.0.1`     |
| `--extensions <list>`          | -                  | 用逗号分隔的协同扩展或商店 URL。                                     | 未设置             |
| `--install [boolean]`          | -                  | 缺失依赖时安装项目依赖。                                           | 按命令默认行为         |
| `--author`                     | `--author-mode`    | 启用维护者诊断信息。                                             | 关闭              |

## 自动化元数据

`start` 会把就绪元数据写入：

* `dist/extension-js/<browser>/ready.json`

在使用 `--no-browser` 时，这对自动化很有用：

* 在启动外部 runner 之前等待 `status: "ready"`。
* 把 `status: "error"` 当作确定性的失败信号处理。
* 用 `runId` 与 `startedAt` 关联某次具体的运行时会话。

### `--no-browser` 与就绪同步

`--no-browser` 只会禁用浏览器启动。它并不会在生产构建完成之前阻塞外部 runner。

对于面向生产的 Playwright、持续集成（CI）和 AI 工作流：

1. 把 `extension start --no-browser` 作为生产者进程。
2. 把 `extension start --wait --browser=<browser>` 作为就绪闸门。
3. 只有在 `status: "ready"` 之后才启动外部浏览器自动化。

`--wait` 在 `error` / 超时时以非零状态退出，并会忽略来自已死进程（`pid` 已不存在）的过期契约。
如果你在同一次调用中同时传入 `--wait` 与 `--no-browser`，`--wait` 优先。命令会以 wait-only 模式运行。

## 日志 flag

| flag                                                 | 作用                                                                           | 默认值      |
| ---------------------------------------------------- | ---------------------------------------------------------------------------- | -------- |
| `--logs <off\|error\|warn\|info\|debug\|trace\|all>` | 最低日志级别。                                                                      | `off`    |
| `--log-context <list\|all>`                          | 上下文过滤（`background`、`content`、`page`、`sidebar`、`popup`、`options`、`devtools`）。 | `all`    |
| `--log-format <pretty\|json\|ndjson>`                | 日志器输出格式。                                                                     | `pretty` |
| `--no-log-timestamps`                                | 在 pretty 模式下关闭时间戳。                                                           | 默认启用时间戳  |
| `--no-log-color`                                     | 在 pretty 模式下关闭颜色。                                                            | 默认启用颜色   |
| `--log-url <pattern>`                                | 按 URL 子串 / 正则过滤日志事件。                                                         | 未设置      |
| `--log-tab <id>`                                     | 按 tab ID 过滤日志事件。                                                             | 未设置      |

## 源代码检视 flag（`start` 不支持）

CLI 会在解析前检测到这些 flag 并以错误退出。请改用 `dev --source ...`。

| flag                                            | 在 `start` 中的支持情况 |
| ----------------------------------------------- | ---------------- |
| `--source [url]`                                | 不支持（命令会带指引退出）    |
| `--watch-source [boolean]`                      | 不支持（命令会带指引退出）    |
| `--source-format <pretty\|json\|ndjson>`        | 不支持（命令会带指引退出）    |
| `--source-summary [boolean]`                    | 不支持（命令会带指引退出）    |
| `--source-meta [boolean]`                       | 不支持（命令会带指引退出）    |
| `--source-probe <selectors>`                    | 不支持（命令会带指引退出）    |
| `--source-tree <off\|root-only>`                | 不支持（命令会带指引退出）    |
| `--source-console [boolean]`                    | 不支持（命令会带指引退出）    |
| `--source-dom [boolean]`                        | 不支持（命令会带指引退出）    |
| `--source-max-bytes <bytes>`                    | 不支持（命令会带指引退出）    |
| `--source-redact <off\|safe\|strict>`           | 不支持（命令会带指引退出）    |
| `--source-include-shadow <off\|open-only\|all>` | 不支持（命令会带指引退出）    |
| `--source-diff [boolean]`                       | 不支持（命令会带指引退出）    |

## 共享的全局选项

也支持 [全局 flag](/docs/workflows/global-flags)。

## 示例

### 用默认浏览器启动

<CodeGroup>
  ```bash npm theme={null}
  extension start
  ```

  ```bash pnpm theme={null}
  extension start
  ```

  ```bash yarn theme={null}
  extension start
  ```

  ```bash bun theme={null}
  extension start
  ```

  ```bash bun theme={null}
  extension start
  ```
</CodeGroup>

### 在 Firefox 中启动

<CodeGroup>
  ```bash npm theme={null}
  extension start --browser firefox
  ```

  ```bash pnpm theme={null}
  extension start --browser firefox
  ```

  ```bash yarn theme={null}
  extension start --browser firefox
  ```

  ```bash bun theme={null}
  extension start --browser firefox
  ```

  ```bash bun theme={null}
  extension start --browser firefox
  ```
</CodeGroup>

### 构建但跳过浏览器启动

<CodeGroup>
  ```bash npm theme={null}
  extension start --no-browser
  ```

  ```bash pnpm theme={null}
  extension start --no-browser
  ```

  ```bash yarn theme={null}
  extension start --no-browser
  ```

  ```bash bun theme={null}
  extension start --no-browser
  ```

  ```bash bun theme={null}
  extension start --no-browser
  ```
</CodeGroup>

## 行为说明

* `start` 不会运行 dev 服务器，也不提供热模块替换（HMR）或 watch 模式。
* `start` 面向生产模式；本地迭代开发请用 `dev`。
* `start` 不支持源代码检视选项。那种工作流请用 `dev --source ...`。
* 对于机器消费者，请解析 `dist/extension-js/<browser>/ready.json`，而不是终端文本。

## 下一步

* 用 [`dev`](/docs/commands/dev) 快速迭代。
* 用 [`preview`](/docs/commands/preview) 启动已有的构建输出。