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

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

在 Android 版 Firefox 上測試

如果要在 Android 版Firefox測試附加元件, 請先設定您的電腦與行動裝置

當你的設備與電腦連線時,你可以使用以下指令:

web-ext run --target=firefox-android

這道指令將會顯示已連線的 Android 設備名稱(device ID)。如果沒有發現設備名稱,請確定有正確地將設備設定至開發者模式。

取得設備名稱(device ID)後,你可以使用以下指令:

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

如果同時擁有多個版本的Firefox,你可能需要在指令中加入版本參數。 例如:

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

當第一次執行此指令時,Android 設備有可能會要求權限。這是因為指令需要存取設備的儲存空間,以便暫存以及執行設定檔(temporary profile) web-ext 命令視窗將會顯示如何取得上述權限。

web-ext 指令將不會對 Android 版 Firefox 現存的檔案做出任何的修改。 想知道更多有關 web-ext 指令對裝置的影響,你可以使用參數 --verbose 來查詢。

參閱 run command 來了解更多參數的使用方法。

在 Android 版 Firefox 上除錯

當你使用 web-ext run 在 Android 版 Firefox 測試附加元件時,你會發現一則類似於以下的訊息:

You can connect to this Android device on TCP port 51499 


這是一個遠端除錯端口,你可以藉由 Firefox's developer tools 來連線。以上述例子來說,你可以在  localhost51499 端口連線。

參考 這則指南 來取得更多有關在 Android 版 Firefox 上除錯的資訊。

測試未經簽章的附加元件

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

使用自訂的設定檔

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

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

這則指令接收 profile 檔案的名稱或是絕對路徑。 在想要手動修改某些設定時是非常有幫助的。

保存修改後的設定檔

一般來說,run 指令不會儲存由 --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 需要有簽章或是指定 manifest.jsonapplications.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) 由 addons.mozilla.org 所指派。下面是一個例子
  • --api-secret: the API secret (JWT secret) 由 addons.mozilla.org 所指派。
  • 舉個例子
    • --api-key:
      user:12345:67
    • --api-secret:
      634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009

參見 sign reference guide 來了解更多。

在沒有 explicit ID 的狀況下進行簽章

web-ext 在簽章時可以不指定在 manifestapplications.gecko.id 的數值。若沒有指定 explicit ID,addons.mozilla.org 會為你產生一個 ID web-ext 會將之紀錄以便往後使用。web-extension-id 存放於工作目錄下。往後在發佈更新時,便可以直接使用。

如果遺失 ID 檔案,在簽章時你必須加上 applications.gecko.id 或使用 --id 指令,以下是一個例子:

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

在網路受限制的情況下進行簽章

如果在部分網域受限制的情況下,你可以嘗試使用proxy 來進行簽章 :

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

參見 --api-proxy 選項來了解更多訊息。

以下的網域是用來進行簽章與下載必要檔案:

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

最後檢查 "lint"

在執行或發佈附加元件於 addons.mozilla.org 前,請使用 lint 指令來檢查 manifest 以及其他原始檔案沒有任何錯誤。以下是一個例子:

web-ext lint

藉由 addons-linter 函式庫來檢查原始碼有無任何錯誤。
Such as the declaration of an unknown permission.

前往 lint reference guide 來了解更多。

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,