> For the complete documentation index, see [llms.txt](https://help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.firstline.cc/feature/admin/kai-fa-yu-zheng-he/huan-jing-bian-shu.md).

# 環境變數

環境變數可集中管理系統整合時重複使用的設定值，並可依資料敏感程度選擇一般變數或機密變數。

## 概述

「環境變數」可用來集中管理系統整合過程中會重複使用的設定值。

例如在 Webhook 或外部服務串接中，可能會重複使用 API 網址、系統識別碼、API Key、Access Token 等資料。透過環境變數，可以先將這些內容集中建立，再於需要的功能中引用，避免相同設定散落在不同位置，也方便日後統一維護。

環境變數分為兩種類型：

| 類型   | 說明                                       |
| ---- | ---------------------------------------- |
| 一般變數 | 適合存放一般設定值，建立後仍可查看目前的內容。                  |
| 機密變數 | 適合存放 API Key、Token、密碼等敏感資訊，建立後無法再次查看原始值。 |

{% hint style="info" %}
如果資料屬於 API Key、Access Token、密碼或其他敏感資訊，建議使用「機密變數」，避免原始內容持續顯示於管理介面。
{% endhint %}

## 進入環境變數管理

具備「系統管理」權限的使用者，可從管理選單進入「環境變數」。

若目前帳號沒有對應的系統管理權限，將不會顯示此管理入口。

進入後，可以查看目前已建立的環境變數，並進行新增、編輯或刪除。

## 新增環境變數

在環境變數管理頁面中，點擊「新增」即可建立新的環境變數。

建立時主要需要設定：

| 欄位   | 說明                        |
| ---- | ------------------------- |
| 名稱   | 環境變數的識別名稱，後續引用此變數時會使用此名稱。 |
| 值    | 此環境變數實際保存的內容。             |
| 機密變數 | 決定此變數是否以機密方式保存。           |

建立前，應先依資料性質決定要使用一般變數或機密變數。

### 一般變數

一般變數適合存放不屬於敏感資訊的設定，例如：

* API 網址
* 固定代碼
* 外部系統識別碼
* 一般文字設定

一般變數建立完成後，之後再次進入編輯頁面時，仍可以查看目前保存的值，也可以直接修改內容。

### 機密變數

機密變數適合存放不應再次顯示的敏感資訊，例如：

* API Key
* Access Token
* 密碼
* 第三方服務密鑰

{% hint style="warning" %}
**機密變數建立後，無法再次查看原始值。**

建立完成後，即使再次進入編輯頁面，系統也不會顯示原本輸入的機密內容。因此，在建立機密變數前，請先確認輸入值正確。
{% endhint %}

如果之後需要更換機密內容，可以重新輸入新的值進行更新，但無法從系統取得先前保存的原始內容。

## 編輯環境變數

已建立的環境變數可以從管理列表進入編輯。

一般變數可以重新查看及修改目前的值。機密變數則不會顯示原本保存的內容；若需要修改，必須重新輸入新的值。

### 機密變數不能改回一般變數

一旦環境變數設定為「機密變數」，之後不能再變更回一般變數。

{% hint style="danger" %}
**機密變數屬於不可逆設定，設定完成後不能再改回一般變數。**

將一般變數改為機密變數前，請先確認後續需求。
{% endhint %}

若原本的機密變數之後確實需要以一般變數方式管理，應另外建立新的環境變數，再調整原有功能的引用設定。

## 修改環境變數名稱

環境變數的「名稱」不只是顯示用途，也可能已經被既有 Webhook 或其他整合設定引用。

因此，修改已經使用中的環境變數名稱可能影響既有流程。

{% hint style="warning" %}
**修改環境變數名稱前，請先確認目前是否已有 Webhook 或其他設定引用此變數。**

若引用位置仍使用原本的名稱，重新命名後可能無法取得對應的環境變數，進而造成相關流程執行失敗。
{% endhint %}

對於已經在正式環境使用的變數，若需要更換名稱，建議先建立新的環境變數，再逐步修改相關引用設定。確認所有使用位置都已完成調整後，再處理舊變數，可降低既有流程中斷的風險。

## 刪除環境變數

不再使用的環境變數可以從管理列表進行刪除。

刪除前應先確認該變數是否仍被 Webhook 或其他整合功能使用。若直接刪除仍有引用的環境變數，相關功能後續可能無法取得所需的設定值。

正式環境中的變數建議依序：

1. 確認目前有哪些功能正在使用此變數。
2. 移除或調整相關引用。
3. 確認相關流程可以正常執行。
4. 再刪除不再使用的環境變數。

## 使用建議

環境變數適合用來管理會被多個整合流程重複使用，或未來可能需要更換的設定資料。

例如，多個 Webhook 都使用同一組外部 API Token 時，可以將 Token 建立為機密環境變數，而不是分別將 Token 寫入每一個 Webhook。日後 Token 更換時，只需要調整環境變數，可降低重複修改與遺漏的風險。

建議依以下原則管理：

* 一般設定值使用一般變數。
* API Key、Token、密碼等敏感內容使用機密變數。
* 已投入使用的環境變數名稱應盡量保持穩定。
* 修改名稱或刪除變數前，先確認既有引用。
* 機密變數建立後無法查看原始值，應另外保留原始密鑰的正式管理來源。
* 機密變數一旦建立，不能再改回一般變數。