> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 用於隔離開發執行的瀏覽器設定檔管理

> 在擴充功能開發期間,透過受管理、持久或自訂路徑的設定檔,控制 Chrome 與 Firefox 的瀏覽器狀態隔離。

在開發期間以受管理、持久或自訂的設定檔,控制瀏覽器狀態的隔離程度。

依照工作流程,讓瀏覽器工作階段保持隔離或持續可重用。Extension.js 啟動瀏覽器時會套用設定檔感知的預設值。可選擇全新的乾淨執行、可重用的狀態,或是明確指定的本地設定檔路徑。

## 運作方式

Extension.js 會依以下順序決定設定檔模式:

1. 明確指定的 `profile` 路徑(若有提供)
2. 受管理設定檔模式(預設)
   * 預設為暫存(短暫)模式
   * 當 `persistProfile: true` 時改為持久模式
3. 當 `EXTENSION_USE_SYSTEM_PROFILE=true` 時使用系統設定檔模式

## 設定檔功能

| 設定 / 選項                             | 用途                           |
| ----------------------------------- | ---------------------------- |
| `browser.<target>.profile`          | 為該瀏覽器目標使用明確指定的設定檔資料夾。        |
| `commands.dev.profile`              | 僅在 `dev` 使用明確指定的設定檔。         |
| `commands.start.profile`            | 僅在 `start` 使用明確指定的設定檔。       |
| `commands.preview.profile`          | 僅在 `preview` 使用明確指定的設定檔。     |
| `browser.<target>.persistProfile`   | 在某個目標的多次執行間重複使用受管理設定檔的狀態。    |
| `commands.<name>.persistProfile`    | 在特定指令情境中重複使用受管理設定檔的狀態。       |
| `--profile=/abs/path`               | CLI 覆寫,明確指定設定檔路徑。            |
| `EXTENSION_USE_SYSTEM_PROFILE=true` | 使用作業系統/瀏覽器的系統設定檔,而不使用受管理設定檔。 |

## 設定檔模式

| 模式      | 啟用方式                                           | 典型用途              |
| ------- | ---------------------------------------------- | ----------------- |
| 受管理暫存   | 預設                                             | 以隔離狀態進行乾淨的執行      |
| 受管理持久   | `persistProfile: true`                         | 以穩定的瀏覽器狀態進行迭代除錯   |
| 明確自訂設定檔 | `profile: "/abs/path"` 或 `--profile=/abs/path` | 重複使用既有的設定檔        |
| 系統設定檔   | `EXTENSION_USE_SYSTEM_PROFILE=true`            | 以作業系統/瀏覽器的預設設定檔啟動 |

Extension.js 會在下列位置建立受管理設定檔:

* `dist/extension-js/profiles/<browser>-profile/<...>`

持久模式使用:

* `dist/extension-js/profiles/<browser>-profile/dev`

## 在 `extension.config.*` 中設定

```js theme={null}
export default {
  browser: {
    chrome: {
      // Use your own profile folder:
      profile: "path/to/custom/profile",
    },
    firefox: {
      // Keep a stable managed profile for repeated sessions:
      persistProfile: true,
    },
  },
};
```

你也可以依指令來設定預設值:

```js theme={null}
export default {
  commands: {
    dev: {
      persistProfile: true,
    },
  },
};
```

## CLI 用法

直接使用明確的設定檔路徑:

```bash theme={null}
extension dev --browser=chrome --profile=/path/to/custom/profile
```

在 `start` 與 `preview` 的用法類似。

## 生命週期說明

* Extension.js 會為每次執行建立暫存的受管理設定檔。
* Extension.js 會在多次執行間重複使用持久的受管理設定檔(`dev`)。
* Extension.js 會自動移除舊的受管理設定檔資料夾。可透過 `EXTENSION_TMP_PROFILE_MAX_AGE_HOURS` 控制最長保留時間。

## 最佳實務

* **以受管理的暫存設定檔做基線測試**:減少隱藏狀態與難以重現的問題。
* **以 `persistProfile` 進行長時間除錯**:在多次執行間保留登入/工作階段/開發者工具狀態。
* **每個瀏覽器家族使用各自的自訂設定檔**:避免跨瀏覽器互相污染。
* **有意識地使用系統設定檔模式**:適合重現問題,但隔離程度不如受管理設定檔。

## 後續步驟

* 進一步了解 [瀏覽器偏好設定](/docs/browsers/browser-preferences)。
* 進一步了解 [瀏覽器旗標](/docs/browsers/browser-flags)。