跳转到主要内容
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。 模板目录里共有 7 组 60 个模板:starters、sidebar、content scripts、new tab、toolbar action、DevTools 面板以及特殊文件夹。运行 extension create --help 查看完整列表。默认的 typescript 模板和其他名称一样会下载模板目录的压缩包。只有 javascript 模板内置在 CLI 里。当你省略 --template、没有设置 EXTENSION_CREATE_TEMPLATE_URL 且下载失败时,create 会回退到内置的 javascript 模板并明确说明,同时给出网络错误,因此离线的机器也能得到一个项目。显式指定的 --template 下载失败则会直接报错。 一个脚手架只有一个包管理器。起步模板的 packageManager 固定值(或它自带的 pnpm-workspace.yaml)决定它,否则由调用 create 的包管理器决定。写入 package.json 的 packageManager 字段、--install 的安装过程以及打印出的后续步骤都指向同一个包管理器。

create 如何选择包管理器

create 在模板写入磁盘之后读取一次包管理器。第一个给出答案的信号胜出: create 从不读取机器上安装了哪些包管理器,也不读取 PATH 上有什么。只有启动命令的包管理器才算数,所以在同时装有 Bun 的机器上,pnpx extension@latest create 得到的是 pnpm 项目。 对于 packageManager 字段,当模板的固定值指向所选的包管理器时,create 会保留它。否则,当启动 create 的包管理器就是所选的包管理器时,它写入该包管理器的版本。两者都没有时,它用 --version 向所选的包管理器询问版本。得不到答案时,create 不写这个字段。在 Deno 上,create 不添加 packageManager 字段。 create 打印的后续步骤使用同一个包管理器: 使用 --install 时,create 自己运行安装,只打印运行步骤。create 写入的 README.md 在其命令中使用同一个包管理器。 使用 --install 时,create 还会安装模板集成所需的构建包,例如 svelte-loader 或 vue-loader。它们装进 Extension.js 工具链的文件夹,而不是你的项目。从 4.1.41 之后的版本起,一次运行就为所有集成安装它们,所以两个集成共用的包只安装一次。不使用 TypeScript 的 Svelte 项目在这次运行中不再获得 typescript。设置 EXTENSION_SKIP_INTERNAL_INSTALL=1 可以跳过这一步。 从 4.1.41 之后的版本起,EXTENSION_CREATE_INSTALL_TIMEOUT_MS 为 create 运行的每次安装设定时间上限,默认 30 分钟。它有自己的变量,所以更长的下载时间上限不会把安装截短。安装超时时,create 会停止它以及它启动的每个进程。随后这次运行失败,原因为 The install did not finish within N seconds。

模板语料的版本固定

模板目录的下载被固定到 templates 仓库的某一个不可变 commit 上。因此同一个版本的两次生成会产生完全相同的字节。有两个环境变量可以覆盖这个固定:
  • EXTENSION_CREATE_TEMPLATE_REF 指向另一个 ref。设为 main 可以恢复浮动行为。
  • EXTENSION_CREATE_TEMPLATE_URL 指向另一个完全不同的压缩包 URL。设置了它而该归档无法使用时,create 会直接失败,永远不会回退到内置模板。
从 4.2.0 之后的版本起,create 会把固定提交的模板目录压缩包保存在每个用户的缓存中。之后从同一个固定版本运行的 create 会从磁盘读取压缩包,不再重新下载。只有当 ref 是完整的 40 位提交 SHA 时才使用缓存,默认的固定版本就是这样。分支、标签或 EXTENSION_CREATE_TEMPLATE_URL 总是会下载。缓存保留最新的 3 个压缩包,损坏的副本会被删除并重新下载。设置 EXTENSION_CREATE_CACHE_DIR 可以移动缓存。默认位置:
  • macOS:~/Library/Caches/extension.js/templates
  • Linux:~/.cache/extension.js/templates 或 $XDG_CACHE_HOME/extension.js/templates
  • Windows:%LOCALAPPDATA%\extension.js\templates
每次生成都会在项目里写入一个 .extension-create.json 溯源文件。它记录 create 的版本、模板和来源,当模板来自模板目录的压缩包时还会记录解析出的 ref,让模板漂移始终可审计。内置的 javascript 起步模板记录的是 "source": "bundled",不带 ref。 每个模板还带有一个供 MCP 客户端读取的 .mcp.json 文件。如果文件夹里已经有 .mcp.json,create 会原样保留它。从 4.1.39 之后的版本起,如果 create 在一个已有的文件夹里中途失败,它会把你的 .gitignore 和 .mcp.json 恢复原样。

用 --output json 得到机器可读输出

--output json 会在 stdout 上打印一个 schema-1 信封,并把生成过程的进度行送到 stderr:
  • 成功的运行会打印一个 status: "created" 帧。它的 value 里带有 projectPath、projectName、template 和 depsInstalled。
  • 从 4.2.0 之后的版本起,value 还带有 packageName,即写入 package.json 的名称。
  • 从 4.2.0 之后的版本起,文件夹保留你输入的名称,任何语言都可以。package.json 在 npm 接受时使用这个名称,在不丢失任何字母或数字时使用清理后的副本(小写、空格变为短横线、去掉标点),否则使用 my-extension,名称不同时运行会说明。只有 node_modules 和 favicon.ico 会作为文件夹名被拒绝,带 E_ARGS,且发生在创建任何内容之前。
  • 失败会打印 ok: false 以及一个 error.code:未知的模板名对应 E_TEMPLATE_NOT_FOUND,下载失败(连接被拒绝、HTTP 错误或超时)对应 E_NETWORK,目标目录的问题对应 E_DESTINATION_NOT_EMPTY 或 E_DESTINATION_NOT_WRITABLE,依赖安装失败对应 E_DEPENDENCY_INSTALL,类型未知的故障对应 E_INTERNAL。
  • 模板 URL 返回的不是 ZIP 归档,或返回的归档已损坏时,会以 E_REMOTE_ZIP_INVALID 失败,并且不会在磁盘上留下任何内容。
  • 归档含有位于其文件夹之外的条目时,同样以 E_REMOTE_ZIP_INVALID 失败,无论它来自模板 URL 还是 EXTENSION_CREATE_TEMPLATE_URL。create 会在写入任何条目之前检查每一个条目,所以消息会说明该归档被拒绝、点名该条目,也不会建议重试。
  • EXTENSION_CREATE_TIMEOUT_MS 限制整个模板拉取的时间,包括重试。超时的拉取以 E_NETWORK 失败,原因为 No answer within N seconds。
  • 失败的 EXTENSION_CREATE_TEMPLATE_URL 永远不会回退到内置的 javascript 模板。返回网页或损坏的归档时以 E_REMOTE_ZIP_INVALID 失败,连接被拒绝、HTTP 错误或超时则以 E_NETWORK 失败。消息会点名这个变量,并且不会在磁盘上留下任何内容。
  • 未设置 EXTENSION_ALLOW_HTTP_TEMPLATE=true 时,普通的 http:// 模板 URL 会以 E_INVALID_OPTION 失败。

共享的全局选项

也支持 全局 flag。

示例命令

可用模板

完整且持续更新的模板列表,请浏览 examples 仓库。

JavaScript

最小的内置起步模板。想要干净基线或处于离线状态时使用。

TypeScript(默认)

带预配置 tsconfig.json 的类型化 sidebar 起步模板。

React

为 content script 与 popup 视图接好线的 React UI。

Vue

内置单文件组件(SFC)支持的 Vue UI。

最佳实践

  • 选择与你的 UI / 运行时需求匹配的模板起步,减少前期设置漂移。
  • 第一次跑得尽量小,等基础命令流验证完再加额外的工具。