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 .


此命令将会实时的监控您的代码文件是否有修改,当您修改保存了您的源代码,它会让浏览器重载入最新的代码. For example, if you changed the name property in your manifest.json file, Firefox would display the new name. This makes it easy to try out new features and see them immediately. To use the automatic reloading feature, start the run command:

web-ext run

If you run into unexpected behavior with the reloading feature, please file a bug. You can also disable reloading like this:

web-ext run --no-reload

Extension reloading is only supported in Firefox 49 or higher.

Testing in different versions of Firefox

To run your extension in a version of Firefox other than the default, use the --firefox option to specify a full path to the binary file. Here is an example on Mac OS:

web-ext run --firefox=/Applications/

On Windows, the path needs to include the firefox.exe part, for example:

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

Testing in Firefox 48

Firefox 48 was the first stable version of the WebExtension platform but it doesn't allow web-ext to install an extension remotely. You need to run your extension in Firefox 48 with a different installation option:

web-ext run --pre-install

Testing unsigned extensions

When you execute web-ext run, the extension gets installed temporarily until you close Firefox. This does not violate any signing restrictions. If instead you create a zip file with web-ext build and try to install it into Firefox, you will see an error telling you that the add-on is not signed. You will need to use an unbranded build or use a development build to install unsigned extensions.

Using a custom profile

By default, the run command will create a temporary Firefox profile. You can run your extension with a specific profile using the --firefox-profile option, like this:

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

This option accepts a string containing the name of your profile or an absolute path to the profile directory.

When using a custom profile, web-ext first copies the profile. The custom profile will not be altered.

Packaging your extension

Once you've tested your extension and verified that it's working, you can turn it into a package for submitting to using the following command:

web-ext build

This will output a full path to the generated .zip file that can be loaded into a browser. It is designed to automatically ignore files that are commonly unwanted in packages, such as .git, node_modules, and other artifacts.

See the build reference guide to learn more.

Distributing your own WebExtension

You can also self-host your package file for distribution but it needs to be signed by Mozilla first. The following command packages and signs a ZIP file, then returns it as a signed XPI file for distribution:

web-ext sign --api-key=yourapikey --api-secret=yourapisecret 

The API options are required to specify your credentials.

  • --api-key: the API key (JWT issuer) from needed to sign the extension. This should always be a string.
  • --api-secret: the API secret (JWT secret) from needed to sign the extension. This should always be a string.

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

Signing extensions without an explicit ID

web-ext fully supports signing extensions that do not declare the property in their manifest. The first time you sign an extension without an explicit ID, 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 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, 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


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