create 会根据所选模板生成文件、配置和起步脚本,并可选地安装依赖。
想逐个文件了解生成的目录树,见 create 会生成什么。
什么时候使用 create
- 从零开始一个新扩展。
- 快速搭出多个概念验证(PoC)。
- 用统一的模板默认值为团队成员标准化上手流程。
create 命令的能力
用法
在用 Yarn?
yarn dlx 命令需要 Yarn 2 或更新版本。Yarn 1 没有
dlx,会以 “Command not found” 错误失败。在 Yarn 1 上,请改用
npm 标签页(npx)。参数与 flag
当你想用默认的 TypeScript 起步模板时,完全省略
--template。只有在想用 官方示例 中其他技术栈时才加上 --template=<slug>。--template 也接受 GitHub URL 或 ZIP URL,因此你可以从任意仓库生成项目。
从 4.1.19 起,模板 URL 必须使用 https://。create 会在写入项目之前拒绝普通的 http:// URL,以及重定向到 http:// 的下载。如果要在你信任的网络中允许 http://,请设置 EXTENSION_ALLOW_HTTP_TEMPLATE=true。
模板目录里共有 6 组 53 个模板:starters、sidebar、content scripts、new tab、toolbar action 以及特殊文件夹。运行 extension create --help 查看完整列表。默认的 typescript 模板和其他名称一样会下载模板目录的压缩包。只有 javascript 模板内置在 CLI 里。当你省略 --template 且下载失败时,create 会回退到内置的 javascript 模板并明确说明,同时给出网络错误,因此离线的机器也能得到一个项目。显式指定的 --template 下载失败则会直接报错。
一个脚手架只有一个包管理器。起步模板的 packageManager 固定值(或它自带的 pnpm-workspace.yaml)决定它,否则由调用 create 的包管理器决定。写入 package.json 的 packageManager 字段、--install 的安装过程以及打印出的后续步骤都指向同一个包管理器。
模板语料的版本固定
模板目录的下载被固定到 examples 仓库的某一个不可变 commit 上。因此同一个版本的两次生成会产生完全相同的字节。有两个环境变量可以覆盖这个固定:EXTENSION_CREATE_TEMPLATE_REF指向另一个 ref。设为main可以恢复浮动行为。EXTENSION_CREATE_TEMPLATE_URL指向另一个完全不同的压缩包 URL。
.extension-create.json 溯源文件。它记录 create 的版本、模板和来源,当模板来自模板目录的压缩包时还会记录解析出的 ref,让模板漂移始终可审计。内置的 javascript 起步模板记录的是 "source": "bundled",不带 ref。
用 --output json 得到机器可读输出
--output json 会在 stdout 上打印一个 schema-1 信封,并把生成过程的进度行送到 stderr:
- 成功的运行会打印一个
status: "created"帧。它的value里带有projectPath、projectName、template和depsInstalled。 - 失败会打印
ok: false以及一个error.code:未知的模板名对应E_TEMPLATE_NOT_FOUND,下载失败对应E_NETWORK,目标目录的问题对应E_DESTINATION_NOT_EMPTY或E_DESTINATION_NOT_WRITABLE。
共享的全局选项
也支持 全局 flag。示例命令
可用模板
JavaScript
最小的内置起步模板。想要干净基线或处于离线状态时使用。
TypeScript(默认)
带预配置
tsconfig.json 的类型化 sidebar 起步模板。React
为 content script 与 popup 视图接好线的 React UI。
Vue
内置单文件组件(SFC)支持的 Vue UI。
最佳实践
- 选择与你的 UI / 运行时需求匹配的模板起步,减少前期设置漂移。
- 第一次跑得尽量小,等基础命令流验证完再加额外的工具。

