MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

Getting started with web-ext

这篇翻译不完整。请帮忙从英语翻译这篇文章

web-ext是一个命令行工具,旨在加速 WebExtension 开发的流程,使开发更快更简单。这篇文章解释了如何安装和使用 web-ext。

安装

web-ext 是一个基于node的应用,你可以安装 nodejs/npm 工具. 安装 web-ext 使用以下命令:

npm install --global web-ext

你可以测试你的安装通过以下命令,列出 web-ext 的版本号:

web-ext --version

使用 web-ext

当您安装完成,您就能立即测试您的扩展功能。如果您没有自己的扩展,可以立刻试试我们的示例,您可以从我们的示例库中复制一份。

测试一个扩展

在命令行 cd 进入 您下载(或您自己开发)的扩展目录 ,然后输入以下命令:

web-ext run

这将启动火狐浏览器并且把扩展临时载入浏览器中, 就相当于您打开了 about:debugging 页面.

进一步学习了解具体用法请跳转到 run reference guide .

自动重新载入扩展

此命令将会实时的监控您的代码文件是否有修改,当您修改保存了您的源代码,它会让浏览器重载入最新的代码。例如,如果你修改了 manifest.json 文件的 name 属性,Firefox 将会展示修改后的 name。这样可以很容易的尝试新的功能并立即看到效果。默认情况下,当你运行下面的命令时,自动重新载入扩展功能是开启的:

web-ext run

你也可以在需要的时候在web-ext命令行界面下使用 r 键以手动触发重新加载的功能。

如果你在使用重新加载时运行了什么问题,请提交这个 bug.。你可以使用下面的命令关闭重新载入功能:

web-ext run --no-reload

重新载入扩展只支持版本 49 或更高的Firefox浏览器。

在不同版本的 Firefox 浏览器中调试

在默认版本以外版本的 Firefox 浏览器调试你的扩展,请使用--firefox 选项并指定 Firefox 浏览器二进制文件的完整路径。这是 Mac OS系统的示例:

web-ext run --firefox=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin

在 Windows系统下,完整路径需要包含 firefox.exe,像这样:

web-ext run --firefox="C:\Program Files\Mozilla Firefox\firefox.exe"

在 Firefox 48 中调试

Firefox 48 是第一个使用 WebExtension 的稳定版本但它并不允许 web-ext 工具直接安装扩展。为了让你的扩展在 Firefox 48 中运行,你需要使用一个不同的安装选项:

web-ext run --pre-install

调试未签名的扩展

当你执行 web-ext run 时,扩展会被临时安装到你的Firefox浏览器中。这样做不会触发任何签名限制。如果直接使用 web-ext build 命令创建一个 zip 文件然后手动将它安装到 Firefox 浏览器中,你会看到一个  that the add-on is not signed 的错误提示。为此你需要使用 unbranded build 或者使用development build 以安装这个未签名的扩展。

使用自定义的配置文件

默认情况下,这个命令行工具会创建一个 Firefox 的临时配置文件。你可以使用 --firefox-profile 选项指定一个特殊的配置文件用以运行你的扩展程序,就像这样:

web-ext run --firefox-profile=chris-work-profile

这条命令接收一个包含配置文件名称的字符串或者这个配置文件所在目录的绝对路径。如果你想配置一些始终可用于运行命令的设置,这可能会有所帮助。

保存配置文件的修改

web-ext 不会保存任何自定义配置文件的修改,除非你使用了 --firefox-profile 选项:

web-ext run --keep-profile-changes --firefox-profile=your-custom-profile

如果你的扩展拥有不同的运行状态的话,这将会对你有帮助。

使用 --firefox-profile 选项会对配置文件进行破坏性的更改,包括添加一些 web-ext 需求的偏好。

打包你的扩展

当你测试完你的扩展并且看到了它能正常工作,你可以使用下面的命令将它打包并提交到 addons.mozilla.org

web-ext build

这会输出一个可以加载到浏览器中的 zip 文件的完整路径。

这个生成的 .zip 文件在没有签名时不能在 Firefox 中正常使用,你也可以添加在 manifest.json文件中添加 applications.gecko.id 。更多信息请参考 WebExtensions and the Add-on ID

web-ext build 被设计为自动忽略一些在文件夹中不被监控的文件例如 .git, node_modules和其他的文件。

查看 build reference guide 了解更多。

为你扩展添加签名以便发布

你可以自行管理你打包的文件用以替代在 addons.mozilla.org 上发布你的扩展,但这样做首先需要 signed by Mozilla 。下面的命令会打包你的文件并为生成的 ZIP 文件添加签名,然后返回一个已签名的 XPI 文件以分发:

web-ext sign --api-key=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET 

这个 API 选项需要的数据可在 addons.mozilla.org credentials 获得:

  • --api-key: the API key (JWT issuer) from addons.mozilla.org needed to sign the extension. 这总是一个字符串。
  • --api-secret: the API secret (JWT secret) from addons.mozilla.org needed to sign the extension. 这总是一个字符串。

查看 sign reference guide 了解这个选项下所有的值。

 

Signing extensions without an explicit ID

web-ext fully supports signing extensions that do not declare the applications.gecko.id property in their manifest. The first time you sign an extension without an explicit ID, addons.mozilla.org will auto-generate an ID and web-ext will save it to .web-extension-id in the current working directory. You should save the ID file so that you can sign future versions of the same extension. If you lose the ID file, you will have to add back the applications.gecko.id property or use the --id option when signing future versions, for example:

web-ext sign --api-key=... --api-secret=... --id="{c23c69a7-f889-447c-9d6b-7694be8035bc}"

Checking for code "lint"

Before trying out your extension with the run command or submitting your package to addons.mozilla.org, you can use the lint command to make sure your manifest and other source files do not contain any errors. Example:

web-ext lint

This uses the addons-linter library to walk through your source code directory and report any errors, such as the declaration of an unknown permission.

See the lint reference guide to learn about all available options.

Specifying different source and destination directories

The above commands all use default directories for the extension source and artifact creation (e.g. built .zip files). The defaults are:

  • Source: The directory you are currently inside.
  • Artifacts: A directory called ./web-ext-artifacts, created inside the current directory.

You can specify different source and destination directories using the --source-dir (or -s alias) and --artifacts-dir (or -a alias) options when running your commands. Their values can be relative or absolute paths, but must always be specified as strings. Here is an example of specifying both options at the same time when  building an extension:

web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips

Outputting verbose messages

If you want to see exactly what web-ext is doing when you run a command, you can include the --verbose option (or the -v alias). For example:

web-ext build --verbose

Viewing all commands and options

You can list all commands and options like this:

web-ext --help

Note: You can also use the -h alias.

You can list options for a specific command by adding it as an argument:

web-ext --help run

See also

文档标签和贡献者

 此页面的贡献者: jinnchen, songyi1999, Meteormatt
 最后编辑者: jinnchen,