翻譯不完整。請協助 翻譯此英文文件

web-ext 是一種用於命令提示字元的工具,用來加速各種擴充套件的開發流程,使開發過程更加簡單快速,以下文章將說明如何安裝與使用web-ext。

安裝

web-ext 是一款基於 node.js 的模組,你可以使用 nodejs/npm 工具去安裝。
安裝 web-ext 的指令如下 :

npm install --global web-ext

web-ext requires the current LTS (long-term support) version of NodeJS.

你可以使用以下指令,藉由顯示 web-ext 的版本號碼來確認安裝是否成功:

web-ext --version

使用 web-ext

在你正式開始使用 web-ext 前,你可以找個附加元件來試試,如果你沒有任何想法,可以到 webextensions-examples 來找一個。

測試你的附加元件

要在firefox測試你的附加套件前,請先將路徑指定到附加元件的根目錄,輸入以下指令:

web-ext run

Firefox  會啟動並將你的附加元件暫時載入, 就像你在 about:debugging page 做的事一樣。

你可以參考 run reference guide 來了解更多細節。

自動重新載入附加元件

run 指令會去檢查原始碼,一旦原始碼儲存後有變更就會重新載入附加元件。舉個例子來說,如果你修改在manifest.json裡面的 name 並儲存,Firefox 就會顯示新的名稱。這使得除錯變得更加容易。一般情況下,此功能預設是開啟的,你也可以使用以下指令:

web-ext run

你也可以在 web-ext 介面中按下 r 鍵來重新載入附加元件。

如果你遇到了無法預期的錯誤,你可以向Firefox回報。 你也可以使用以下指令來停止重新載入功能:

web-ext run --no-reload

請注意,自動重新載入只支援 Firefox 49 或以上版本。

在不同的Firefox版本測試你的附加元件

若要在不同的版本上執行你的附加元件, 請使用 --firefox 選項,並給予明確的二進制檔路徑。以下是 Mac OS 的範例:

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

在Windows下, 路徑需要指向 firefox.exe,以下是 Windows 的範例:

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

參考 run command 來了解更多有關參數的用法。

在FireFox 48 上測試

Firefox 48 是第一個使用新版附加元件的穩定版本,但在此版本並不允許藉由 web-ext 來安裝附加元件. 你需要藉由以下指令來在 Firefox 48 上執行你的附加元件:

web-ext run --pre-install

Testing in Firefox for Android

To run your extension in Firefox for Android, follow these instructions to set up your computer and device.

With your device connected to your development computer, run:

web-ext run --target=firefox-android

This command displays the device ID for your connected Android device or devices. If you don't see a list of device IDs, make sure you set up the device for development correctly.

Now, add the device ID to the command:

web-ext run --target=firefox-android --android-device=<device ID>

If you've multiple versions of Firefox installed, you may need to choose a specific version. For example:

web-ext run --target=firefox-android ... --firefox-apk=org.mozilla.firefox

The first time you run this command, you may need to grant Android permissions for the APK. This is because the command needs read / write access to the device storage, so that Firefox for Android can run on a temporary profile. The web-ext output guides you in how to grant these permissions.

The web-ext command does not alter any of your existing Firefox for Android preferences or data. To see more information about how web-ext is interacting with your device, run the command with --verbose.

See the run command reference to learn more.

Debugging in Firefox for Android

When using web-ext run to test an extension on Firefox for Android, you'll notice a message like this in the console output:

You can connect to this Android device on TCP port 51499 

This is a remote debugger port that you can connect to with Firefox's developer tools. In this case, you'd connect to host localhost on port 51499.

See this guide for more information about debugging an extension on Firefox for Android.

測試未經簽章的附加元件

當你執行 web-ext run,附加元件就會暫時地安裝在Firefox中,直到你關閉瀏覽器。如果你藉由 web-ext build 建立了 zip 檔案,在安裝時你會發現附加元件沒有正確的數位簽章。 你需要使用 unbranded builddevelopment build 來安裝未經簽章的附加元件。

使用自訂的設定檔

在一般狀況下,run 指令會創建一個暫時的設定檔。 要指定特定的設定檔,請使用--firefox-profile 參數, 下面是一個例子:

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

This option accepts a string containing the name of your profile or an absolute path to the profile directory. This is helpful if you want to manually configure some settings that will always be available to the run command.

Keeping profile changes

The run command does not save any changes made to the custom profile specified by --firefox-profile. To keep changes, add this option:

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

This may be helpful if your extension has many different run states.

This option makes the profile specified by --firefox-profile completely insecure for daily use. It turns off auto-updates and allows silent remote connections, among other things. Specifically, it will make destructive changes to the profile that are required for web-ext to operate.

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 addons.mozilla.org using the following command:

web-ext build

This outputs a full path to the generated .zip file that can be loaded into a browser.

The generated .zip file doesn't work on Firefox without signing or adding applications.gecko.id key into manifest.json.  For more information, please refer WebExtensions and the Add-on ID page.

web-ext build is designed to ignore files that are commonly not wanted in packages, such as .git, node_modules, and other artifacts.

See the build reference guide to learn more.

Signing your extension for distribution

As an alternative to publishing your extension on addons.mozilla.org, you can self-host your package file 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=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET 

The API options are required to specify your addons.mozilla.org credentials.

  • --api-key: the API key (JWT issuer) from addons.mozilla.org needed to sign the extension. This is a string that will look something like user:12345:67.
  • --api-secret: the API secret (JWT secret) from addons.mozilla.org needed to sign the extension. This is a string that will look something like 634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009.

See the sign reference guide to learn more.

Signing extensions without an explicit ID

web-ext 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 generate an ID and web-ext will save it to .web-extension-id in the 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, for example:

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

Signing in a restricted environment

If you're working in an environment that restricts access to certain domains, you can try using a proxy when signing:

web-ext sign --api-key=... --api-secret=... --api-proxy=https://yourproxy:6000

See the --api-proxy option to learn more.

The following domains are used for signing and downloading files:

  • addons.mozilla.org
  • addons.cdn.mozilla.net

Checking for code "lint"

Before trying out your extension with the run command or submitting your package to addons.mozilla.org, 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 more.

Setting option defaults in a configuration file

You can specify --config=my-config.js to set default values for any option. Here is an example with the build command:

web-ext --config=my-config.js build

The file should be a CommonJS module as understood by NodeJS and must export each configuration value. Here is how you would set the default value of --verbose to true:

module.exports = {
  verbose: true,
};

If you want to specify options that only apply to a specific command, you nest the configuration under the command name. Here is an example of adding configuration for --overwrite-dest that only applies to the build command as well as --firefox that only applies to the run command:

module.exports = {
  // Global options:
  verbose: true,  
  // Command options:
  build: {
    overwriteDest: true,
  },
  run: {
    firefox: 'nightly',
  },
};

To create a configuration key for a command line option, you remove the preceding dashes and convert the name to camel case. As you can see from this example, --overwrite-dest was converted to overwriteDest.

If an option can be specified multiple times on the command line then you define it as an array. For example, here is how to specify multiple --ignore-files patterns:

module.exports = {
  ignoreFiles: [
    'package-lock.json',
    'yarn.lock',
  ],
};

Automatic discovery of configuration files

web-ext will load existing configuration files in the following order:

  • A config file named .web-ext-config.js in your home directory, for example:
    • On Windows: C:\Users\<username>\.web-ext-config.js
    • On macOS: /Users/<username>/.web-ext-config.js
    • On Linux: /home/<username>/.web-ext-config.js
  • A config file named web-ext-config.js in the current directory.

If a home directory config and a local directory config define the same option, the value from the latter file will be used.

To disable automatic loading of configuration files, set this option:

web-ext --no-config-discovery run

To diagnose an issue related to config files, re-run your command with --verbose. This will tell you which config file affected which option value.

Specifying different source and destination directories

The preceding commands use default directories for the extension source and artifact creation (for example, built .zip files). The defaults are:

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

You can specify different source and destination directories using the --source-dir and --artifacts-dir 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 when building an extension:

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

Outputting verbose messages

To see in detail what web-ext is doing when you run a command, include the --verbose option. For example:

web-ext build --verbose

Viewing all commands and options

You can list all commands and options like this:

web-ext --help

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

web-ext --help run

Detecting temporary installation

Your extension can detect whether it was installed using web-ext run, rather than as a built and signed extension downloaded from addons.mozilla.org. Listen for the runtime.onInstalled event and check the value of details.temporary.

Using web-ext from a script

You can use web-ext as a NodeJS module. Here is more information, with example code.

See also

文件標籤與貢獻者

此頁面的貢獻者: Dkal
最近更新: Dkal,