在擴充功能中使用 ECMAScript modules

在所有擴充功能情境中以現代的 import/export 語法撰寫程式碼。 Extension.js 在背景 script、content script 與擴充功能頁面都支援 ECMAScript Modules（ESM），並使用預設的 Rspack pipeline 進行模組解析。

什麼情況下適合使用 ESM

你希望擴充功能與 web 端的程式碼採用一致的模組語法。
你正在與以 ESM 為主的現代套件共用程式碼。
你需要更乾淨的 tree-shaking（自動移除未使用的程式碼）與明確的相依界線。

範本範例

`new`

以現代模組語法與最少設定開始一個 new-tab 擴充功能。

npx extension@latest create my-extension --template=new

pnpx extension@latest create my-extension --template=new

yarn dlx extension@latest create my-extension --template=new

bunx extension@latest create my-extension --template=new

bunx extension@latest create my-extension --template=new

Repository: extension-js/examples/new

`content`

在維持 ESM 風格撰寫的同時，把 script 邏輯注入頁面內容。

npx extension@latest create my-extension --template=content

pnpx extension@latest create my-extension --template=content

yarn dlx extension@latest create my-extension --template=content

bunx extension@latest create my-extension --template=content

bunx extension@latest create my-extension --template=content

Repository: extension-js/examples/content

在既有擴充功能中使用

你可以直接在擴充功能原始碼檔案（.js、.mjs、.ts、.tsx 等）中使用 ESM 語法，不需要額外的打包設定。如果你的 Node.js 專案設定檔也要以 ESM 執行，請在 package.json 中設定 "type": "module"。這適用於自訂 script 與設定慣例：

{
  "name": "my-extension",
  "version": "1.0",
  "description": "My Extension Example",
  "type": "module",
  "devDependencies": {
    "extension": "latest"
  },
  "scripts": {
    "dev": "extension dev",
    "start": "extension start",
    "build": "extension build"
  }
}

Manifest 與 service worker 注意事項

對於 Manifest V3 的背景 worker：

想要在 service worker 中以原生 ES module 載入時，請把 background.type 設為 "module"。
若未指定 module worker type，Extension.js 會採用 classic worker 載入方式（打包後的 script，不使用原生 module 語法）。

{
  "background": {
    "service_worker": "src/background.ts",
    "type": "module"
  }
}

ESM 與 CommonJS 提醒

撰寫 ESM 模組時：

相對匯入要加上副檔名

// my-file.mjs
import React from 'react'

// local imports
- import myImport from './myImport'
+ import myImport from './myImport.js'

與非 ESM 模組的互通性可能不同

從 ESM 匯入 CommonJS 套件時，請依照各套件提供的相容性建議。

嚴格 ESM 情境下沒有 CommonJS 全域變數

請避免在 ESM 模組中使用 require、module.exports、__filename 與 __dirname。

在 ECMAScript modules 中處理環境變數

Extension.js 同時支援：

process.env.EXTENSION_PUBLIC_*
import.meta.env.EXTENSION_PUBLIC_*

希望在擴充功能程式碼中可用的變數，請使用 EXTENSION_PUBLIC_ 前綴。

// example.mjs

console.log(import.meta.env.EXTENSION_PUBLIC_API_KEY);
console.log(process.env.EXTENSION_PUBLIC_API_KEY);

import 一定要寫副檔名嗎？

Node.js 在 ESM import specifier 中要求明確的副檔名（要寫 import "./util.js"，不能寫 import "./util"）。這條規則適用於 Node 直接執行的程式碼，常常會讓從 server 端轉到擴充功能的人感到困惑。在 Extension.js 裡，解析 import 的是打包工具而不是 Node，因此擴充功能程式碼中兩種寫法都可以：

import { parse } from "./util"; // 由打包工具解析
import { parse } from "./util.js"; // 也沒問題

Node 規則仍然重要的兩個情境是：

package.json 中以 Node 直接執行的 script（建置輔助、程式碼產生）：那裡副檔名是必要的。
在 Node 工具與擴充功能程式碼之間共用的 .mjs 檔：撰寫時要讓兩種解析器都能接受。

下一步

進一步了解 TypeScript。
探索 Extension.js 如何處理 CSS modules。

影片導覽

在瀏覽器擴充功能中使用 TypeScript 在瀏覽器擴充功能中使用 React

⌘I

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Debugging

Implementation guide

Community

在擴充功能中使用 ECMAScript modules

什麼情況下適合使用 ESM

範本範例

`new`

`content`

在既有擴充功能中使用

Manifest 與 service worker 注意事項

ESM 與 CommonJS 提醒

相對匯入要加上副檔名

與非 ESM 模組的互通性可能不同

嚴格 ESM 情境下沒有 CommonJS 全域變數

在 ECMAScript modules 中處理環境變數

import 一定要寫副檔名嗎？

下一步

影片導覽

​什麼情況下適合使用 ESM

​範本範例

​new

​content

​在既有擴充功能中使用

​Manifest 與 service worker 注意事項

​ESM 與 CommonJS 提醒

​相對匯入要加上副檔名

​與非 ESM 模組的互通性可能不同

​嚴格 ESM 情境下沒有 CommonJS 全域變數

​在 ECMAScript modules 中處理環境變數

​import 一定要寫副檔名嗎？

​下一步

​影片導覽

什麼情況下適合使用 ESM

範本範例

`new`

`content`

在既有擴充功能中使用

Manifest 與 service worker 注意事項

ESM 與 CommonJS 提醒

相對匯入要加上副檔名

與非 ESM 模組的互通性可能不同

嚴格 ESM 情境下沒有 CommonJS 全域變數

在 ECMAScript modules 中處理環境變數

import 一定要寫副檔名嗎？

下一步

影片導覽