> ## 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. # 用 preview 命令启动已构建的扩展 > 无需重新编译，启动一个已构建好的扩展进行类生产的手动测试。加载未打包的输出并运行浏览器启动流程。 启动一个已构建的扩展输出，进行类生产的手动测试。 `preview` 不会编译你的项目。它会加载一个已存在的未打包扩展根目录，并运行浏览器启动流程。 ## 什么时候使用 `preview` * 想运行已有的构建输出，而不重新构建。 * 快速对比已打包行为在多个浏览器目标上的表现。 * 调试与生产产物相关、而非与 dev / watch 模式相关的运行时问题。 ## preview 命令的能力 | 能力 | 你得到什么 | | --------- | ---------------------- | | 构建输出验证 | 不重新构建即可测试真实的生产产物 | | 浏览器目标检查 | 在所选浏览器目标上运行已编译的输出 | | runner 控制 | 根据工作流需要启动或跳过浏览器 runner | | 快速手动 QA | 发布前快速验证打包就绪的行为 | > `preview` 是 run-only 的。它会优先使用已存在的 `dist/`。你也可以让它指向其他已包含 `manifest.json` 的未打包扩展文件夹。 ## 用法 ```bash npm theme={null} extension preview [project-path] [options] ``` ```bash pnpm theme={null} extension preview [project-path] [options] ``` ```bash yarn theme={null} extension preview [project-path] [options] ``` ```bash bun theme={null} extension preview [project-path] [options] ``` ```bash bun theme={null} extension preview [project-path] [options] ``` 如果省略路径，Extension.js 会使用当前工作目录。 ## `preview` 如何决定运行哪个目录 `preview` 按以下顺序检查： 1. 所选浏览器目标对应的 `dist/`。 2. 提供的项目路径或当前工作目录。 该文件夹需要包含一个带 `manifest.json` 的未打包扩展。是否在同一条命令里跑过 `build` 并不重要。 ## 参数与 flag | flag | 别名 | 作用 | 默认值 | | --------------------------- | ------------------ | --------------------------------------------------------------- | --------------- | | `[path]` | - | 从项目路径预览已构建的扩展。 | `process.cwd()` | | `--browser ` | - | 浏览器 / 引擎目标（`chromium`、`chrome`、`edge`、`firefox` 等）。 | `chromium` | | `--profile ` | - | 浏览器 profile 路径或布尔的 profile 模式。 | 全新 profile | | `--chromium-binary ` | - | [自定义的 Chromium 家族二进制路径](/docs/browsers/running-other-browsers)。 | 系统默认 | | `--gecko-binary ` | `--firefox-binary` | [自定义的 Gecko 家族二进制路径](/docs/browsers/running-other-browsers)。 | 系统默认 | | `--starting-url ` | - | 启动浏览器时的起始 URL。 | 未设置 | | `--no-browser` | - | 跳过浏览器启动。 | 默认启用浏览器启动 | | `--port ` | - | 启用 runner 时使用的 runner / devtools 端口。用 `0` 让 OS 自动分配端口。 | `8080` | | `--host ` | - | 绑定 dev 服务器的主机。Docker / dev container 中可用 `0.0.0.0`。 | `127.0.0.1` | | `--extensions ` | - | 用逗号分隔的协同扩展或商店 URL。 | 未设置 | | `--author` | `--author-mode` | 启用维护者诊断信息。 | 关闭 | ## 自动化元数据 `preview` 会把就绪元数据写入： * `dist/extension-js//ready.json` 对于 `--no-browser` 流程，它提供了确定性的命令状态： * 命令初始化时为 `starting` * run-only 验证完成时为 `ready` * 缺少所需输出或启动失败时为 `error` * `runId` 与 `startedAt` 用于在脚本 / agent 中做会话关联 `preview` 不提供 `--wait` 闸门 flag。`preview` 的自动化请直接消费 `ready.json`。 ## 日志 flag | flag | 作用 | 默认值 | | ---------------------------------------------------- | ---------------------------------------------------------------------------- | -------- | | `--logs ` | 最低日志级别。 | `off` | | `--log-context ` | 上下文过滤（`background`、`content`、`page`、`sidebar`、`popup`、`options`、`devtools`）。 | `all` | | `--log-format ` | 日志器输出格式。 | `pretty` | | `--no-log-timestamps` | 在 pretty 模式下关闭时间戳。 | 默认启用时间戳 | | `--no-log-color` | 在 pretty 模式下关闭颜色。 | 默认启用颜色 | | `--log-url ` | 按 URL 子串 / 正则过滤日志事件。 | 未设置 | | `--log-tab ` | 按 tab ID 过滤日志事件。 | 未设置 | ## 源代码检视 flag（`preview` 不支持） CLI 会在解析前检测到这些 flag 并以错误退出。请改用 `dev --source ...`。 | flag | 在 `preview` 中的支持情况 | | ----------------------------------------------- | ------------------ | | `--source [url]` | 不支持（命令会带指引退出） | | `--watch-source [boolean]` | 不支持（命令会带指引退出） | | `--source-format ` | 不支持（命令会带指引退出） | | `--source-summary [boolean]` | 不支持（命令会带指引退出） | | `--source-meta [boolean]` | 不支持（命令会带指引退出） | | `--source-probe ` | 不支持（命令会带指引退出） | | `--source-tree ` | 不支持（命令会带指引退出） | | `--source-console [boolean]` | 不支持（命令会带指引退出） | | `--source-dom [boolean]` | 不支持（命令会带指引退出） | | `--source-max-bytes ` | 不支持（命令会带指引退出） | | `--source-redact ` | 不支持（命令会带指引退出） | | `--source-include-shadow ` | 不支持（命令会带指引退出） | | `--source-diff [boolean]` | 不支持（命令会带指引退出） | ## 共享的全局选项 也支持 [全局 flag](/docs/workflows/global-flags)。 ## 示例 ### 预览一个本地扩展 ```bash npm theme={null} extension preview ./my-extension ``` ```bash pnpm theme={null} extension preview ./my-extension ``` ```bash yarn theme={null} extension preview ./my-extension ``` ```bash bun theme={null} extension preview ./my-extension ``` ```bash bun theme={null} extension preview ./my-extension ``` ### 在 Edge 与 Chrome 中预览 ```bash npm theme={null} extension preview ./my-extension --browser=edge,chrome ``` ```bash pnpm theme={null} extension preview ./my-extension --browser=edge,chrome ``` ```bash yarn theme={null} extension preview ./my-extension --browser=edge,chrome ``` ```bash bun theme={null} extension preview ./my-extension --browser=edge,chrome ``` ```bash bun theme={null} extension preview ./my-extension --browser=edge,chrome ``` ### 不启动浏览器进行预览 ```bash npm theme={null} extension preview ./my-extension --no-browser ``` ```bash pnpm theme={null} extension preview ./my-extension --no-browser ``` ```bash yarn theme={null} extension preview ./my-extension --no-browser ``` ```bash bun theme={null} extension preview ./my-extension --no-browser ``` ```bash bun theme={null} extension preview ./my-extension --no-browser ``` ## 行为说明 * `preview` 是 run-only 的，永远不会编译项目。 * `preview` 优先使用已有的构建输出（`dist/`），但也可以回落到另一个未打包扩展根目录。 * `preview` 不会运行 watch 模式，也不提供热模块替换（HMR）。 * `preview` 不支持源代码检视 flag；那种工作流请用 `dev`。 * 对于脚本 / agent，请依赖 `ready.json`，避免解析终端输出。 ## 最佳实践 * 测试新鲜的生产产物时，先跑 `build` 再跑 `preview`。 * 当你的未打包扩展位于默认项目输出之外时，请传入项目路径参数。 * 打包前用 `--browser` 在多个目标上验证行为。 ## 下一步 * 一步构建并启动：用 [`start`](/docs/commands/start)。 * 生成生产产物：用 [`build`](/docs/commands/build)。 * 在 [`extension.config.js`](/docs/features/extension-configuration) 中集中配置共享默认值。 * 在 [环境变量](/docs/features/environment-variables#how-it-works) 中查看配置期 env 加载行为。