本頁面由 Cloud Translation API 翻譯而成。

建立自訂範本

Firebase Studio 提供各種內建範本，包含所有檔案、系統套件 (例如編譯器) 和擴充功能，可協助您快速開始使用特定語言或架構。

您也可以使用 GitHub 上託管的社群範本，啟動 Firebase Studio 工作區。如要進一步瞭解如何從範本啟動新工作區，請參閱「建立Firebase Studio工作區」。

大多數使用者會使用內建範本或從 Git 匯入專案，但如要處理更進階的用途，可以自行建立範本：

如果您要建構自己的架構、程式庫或服務，可以讓使用者充分運用雲端虛擬機器的強大功能，在不離開瀏覽器的情況下，快速開始使用您的技術。
如果您有偏好的專案技術堆疊，可以使用自訂範本簡化啟動新專案的程序。
如果您要教導他人，例如透過教學課程或程式碼研究室，可以預先將程式碼研究室的起點設為自訂範本，為學生移除部分初始步驟。

建立及測試自訂範本後，您可以建立範本的連結，並將連結放在網站、Git 存放區 README 檔案、套件詳細資料頁面 (例如 NPM) 或任何其他位置，方便使用者開始使用您的技術。

事前準備

事前準備作業：

瞭解如何使用 idx/dev.nix 檔案自訂環境。
熟悉 Nix 語言基本概念，並隨時參考相關資料。

範本檔案結構

Firebase Studio 範本是公開的 Git 存放區 (或存放區中的資料夾或分支)，至少包含兩個檔案：

idx-template.json 包含範本的中繼資料，包括使用者可見的名稱、說明，以及使用者可用的參數，用於設定範本。舉例來說，您可以讓使用者從多種程式設計語言或範例用途中選擇。Firebase Studio 會使用這項資訊，在使用者選擇從範本建立新工作區時，準備向他們顯示的 UI。
idx-template.nix 是以 Nix 語言編寫的檔案，內含 Bash 殼層指令碼 (包裝在 Nix 函式中)，可執行下列操作：
1. 為新工作區建立工作目錄。
2. 建立 .idx/dev.nix 檔案來設定環境。請注意，您也可以在這個指令碼中執行專案架構工具 (例如 flutter create 或 npm init)，或執行以 Go、Python、Node.js 或其他語言編寫的自訂指令碼。
  
  Firebase Studio 載入範本時，系統會使用使用者指定的參數執行這個檔案。

除了這兩個檔案，您也可以加入其他檔案，在 idx-template.nix 中使用，以便例項化範本。舉例來說，您可以加入最終 .idx/dev.nix 檔案，甚至將所有架構檔案直接加入存放區。

建立入門範本

為加快範本建立速度，建議您先透過下列其中一種方法建立 Firebase Studio 範本，然後再進一步自訂：

將任何公開 GitHub 存放區變成範本
以官方或社群範本為基礎建立範本

基本範例：將任何公開 GitHub 存放區變成範本

在深入瞭解如何定義 idx-template.json 和 idx-template.nix 之前，不妨先看看基本範本範例，瞭解如何：

不含使用者可設定的參數。
將範本存放區中的所有檔案 (兩個 idx-template 檔案除外) 複製到使用者的工作區。應該已經有 .idx 子資料夾，其中包含定義環境的 dev.nix 檔案。

如果您將下列檔案新增至任何公開 GitHub 存放區 (或子資料夾或分支)，該存放區就會變成Firebase Studio範本。

`idx-template.json`

{
  "name": "Hello world",
  "description": "A template for a CLI program that prints 'hello world'",
  "icon": "https://www.gstatic.com/images/branding/productlogos/studio/v1/192px.svg",
  "params": []
}

`idx-template.nix`

# No user-configurable parameters
{ pkgs, ... }: {
  # Shell script that produces the final environment
  bootstrap = ''
    # Copy the folder containing the `idx-template` files to the final
    # project folder for the new workspace. ${./.} inserts the directory
    # of the checked-out Git folder containing this template.
    cp -rf ${./.} "$out"

    # Set some permissions
    chmod -R +w "$out"

    # Remove the template files themselves and any connection to the template's
    # Git repository
    rm -rf "$out/.git" "$out/idx-template".{nix,json}
  '';
}

請參閱「自訂範本」一文，瞭解如何進一步變更範本。

使用官方或社群範本建立自訂範本

Firebase Studio 團隊維護兩個範本存放區：Firebase Studio

官方範本：建立新應用程式時，您可以直接從資訊主頁選取這些範本。Firebase Studio
社群範本：這些範本可讓開放原始碼社群貢獻內容。如要使用社群範本，請複製社群範本 Git 存放區。你可以使用要使用的範本完整連結。

提示： 如要新增範本或更新現有範本，為社群貢獻心力，請提交提取要求。

如要以現有範本為基礎建立自訂範本，請按照下列步驟操作：

決定要以哪個範本做為自訂範本的基礎，然後複製專案。
視需要自訂 idx-template.json、idx-template.nix 和 .idx/dev.nix，首先請參閱「自訂範本」。
將變更簽入存放區。
請按照「為範本建立新工作區」一文的說明，發布及測試範本。如果使用巢狀存放區，請在網址中直接連結至該存放區。舉例來說，如果您使用「Vanilla Vite」社群範本，可以透過下列網址佈建及測試新工作區：
```
https://studio.firebase.google.com/new?template=https://github.com/firebase-studio/community-templates/tree/main/vite-vanilla
```

請參閱「自訂範本」一文，瞭解如何進一步變更範本。

自訂範本

您已建立基本範本，現在可以根據需求編輯 idx-template.json、idx-template.nix 和 .idx/dev.nix 檔案。您可能需要自訂其他設定：

將系統套件新增至 bootstrap 指令碼。
新增使用者可設定的參數
選擇要預設開啟的檔案
選擇預設工作區圖示

在 `bootstrap` 指令碼中使用其他系統套件

基本範例只會使用基本 POSIX 指令，將檔案複製到正確位置。範本的 bootstrap 指令碼可能需要安裝其他二進位檔，例如 git、node、python3 或其他檔案。

如要讓啟動程序指令碼使用其他系統套件，請在 idx-template.nix 檔案中指定 packages，就像在 dev.nix 檔案中將其他系統套件新增至 packages，藉此自訂工作區一樣。

以下範例是新增 pkgs.nodejs，其中包含 node、npx 和 npm 等二進位檔：

# idx-template.nix
{pkgs}: {
  packages = [
    # Enable "node", "npm" and "npx" in the bootstrap script below.
    # Note, this is NOT the list of packages available to the workspace once
    # it's created. Those go in .idx/dev.nix
    pkgs.nodejs
  ];

  bootstrap = ''
    mkdir "$out"
    # We can now use "npm"
    npm init --yes my-boot-strap@latest "$out"
  ''
}

新增可由使用者設定的參數

如要讓使用者自訂新專案的起點，您可以建立多個範本，或建立含有參數的單一範本。如果不同的起點只是傳遞至 CLI 工具的不同值 (例如 --language=js 與 --language=ts)，這個選項就非常適合。

如要新增參數，請按照下列步驟操作：

在 idx-template.json 中繼資料檔案的 params 物件中說明參數。Firebase Studio 會使用這個檔案中的資訊準備 UI (例如核取方塊、下拉式選單和文字欄位)，供範本使用者查看。
更新 idx-template.nix 啟動程序，使用使用者在例項化範本時選取的值。

在 `idx-template.json` 中說明參數

以下範例說明如何新增 enum 參數，Firebase Studio 會根據選項數量顯示為下拉式選單或圓形按鈕群組：

{
  "name": "Hello world",
  "description": "A hello world app",
  "params": [
    {
      "id": "language",
      "name": "Programming Language",
      "type": "enum",
      "default": "ts",
      "options": {
        "js": "JavaScript",
        "ts": "TypeScript"
      },
      "required": true
    }
  ]
}

由於有兩個值 (JavaScript 和 TypeScript)，UI 會為這兩個選項算繪單選按鈕群組，並將 ts 或 js 值傳遞至 idx-template.nix 指令碼。

每個參數物件都具有下列屬性：

屬性	類型	說明
id	`string`	參數的專屬 ID，類似於變數名稱。
名稱	`string`	這個參數的顯示名稱。
類型	`string`	指定要用於這個參數的 UI 元件，以及要傳遞至啟動程序指令碼的資料類型。以下為有效值： `"enum"` - 顯示下拉式選單或圓形按鈕群組，並將 `string` 傳遞至 Bootstrap `"boolean"` - 顯示核取方塊和通過的票證 `true` 或 `false` `"text"` - 顯示文字欄位並傳遞 `string`
選項	`object`	如果是 `enum` 參數，這代表要向使用者顯示的選項。舉例來說，如果選項是 `{"js": "JavaScript", ...}`，「JavaScript」會顯示為選項，選取後這個參數的值會是 `js`。
預設	`string`或`boolean`	在 UI 中設定初始值。如果是 `enum` 參數，則必須是 `options` 中的其中一個鍵。如果是 `boolean` 參數，則應為 `true` 或 `false`。
必填	`boolean`	表示這是必要參數。

在 `idx-template.nix` 中使用參數值

在 idx-template.json 檔案中定義 params 物件後，您就可以根據使用者選擇的參數值，開始自訂啟動程序指令碼。

延續上一節的範例，如果您有一個 ID 為 language 的單一參數，且該參數是可能值為 ts 或 js 的列舉，則可以這樣使用：

# idx-template.nix
# Accept additional arguments to this template corresponding to template
# parameter IDs, including default values (language=ts by default in this example).
{ pkgs, language ? "ts", ... }: {
  packages = [
    pkgs.nodejs
  ];

  bootstrap = ''
    # We use Nix string interpolation to pass the user's chosen programming
    # language to our script.
    npm init --yes my-boot-strap@latest "$out" -- --lang=${language}
  ''
}

另一個常見模式是根據字串的值，有條件地加入內容。前述範例的另一種寫法是：

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

選擇預設開啟的檔案

建議您自訂使用範本建立新工作區時要開啟哪些檔案進行編輯。舉例來說，如果範本適用於基本網站，您可能需要開啟主要的 HTML、JavaScript 和 CSS 檔案。

如要自訂預設開啟的檔案，請更新 .idx/dev.nix 檔案 (不是 idx-template.nix 檔案！)，加入含有 openFiles 屬性的 onCreate 工作區掛鉤，如下所示：

# .idx/dev.nix
{pkgs}: {
  ...
  idx = {
    # Workspace lifecycle hooks
    workspace = {
      # Runs when a workspace is first created with this `dev.nix` file
      onCreate = {
        # Open editors for the following files by default, if they exist.
        # The last file in the list will be focused.
        default.openFiles = [
          "src/index.css"
          "src/index.js"
          "src/index.html"
        ];
        # Include other scripts here, as needed, for example:
        # installDependencies = "npm install";
      };
      # To run something each time the workspace is (re)started, use the `onStart` hook
    };
    # Enable previews and customize configuration
    previews = { ... };
  };
}

選擇預設工作區圖示

如要為使用範本建立的工作區選擇預設圖示，請將名為 icon.png 的 PNG 檔案放在 .idx 目錄中，與 dev.nix 檔案並列。

在新工作區中測試範本

如要測試範本的完整流程，最簡單的方法就是使用範本建立新的工作區。請前往下列連結，並將範例替換成範本的 GitHub 存放區網址：

https://idx.google.com/new?template=https://github.com/my-org/my-repo

您可以視需要加入分支和子資料夾。只要可公開存取，下列網址都有效：

https://github.com/my-org/my-repo/
https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplate
https://github.com/my-org/my-repo/tree/branch
https://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate

您也可以將這個網址分享給其他人，讓他們使用新的範本，或從「在 Firebase Studio 中開啟」按鈕連結至這個網址。

確認範本運作正常後，請將範本發布至 GitHub 存放區，並分享您建立測試用工作區時使用的連結。

如要讓使用者更容易找到範本，請在網站或存放區 README 中新增「在<產品名稱> 中開啟」按鈕Firebase Studio。