既然你已經從 Web App 遷移到 Azure Container Apps (ACA)，網路架構的邏輯會稍微有些不同。ACA 本身就是建立在一個名為 Container Apps Environment 的容器環境中，因此 VNet 的整合是在「環境 (Environment)」層級設定的，而不是單獨在特定的 App 上。

存取 VNet 資源的流程主要分為：環境網路配置、基礎架構委派、以及 ACA 部署。

1. 核心觀念：VNet 整合模式

ACA 支援兩種網路模式：

• External (外部)：環境有公網 IP，但後端可以存取 VNet 資源。
• Internal (內部)：環境沒有公網 IP，所有存取都必須透過 VNet（適合純內網系統）。

2. 實作流程與 CLI 指令

第一步：建立（或準備）Subnet 並設定委派

與 Web App 相似，ACA 的 Subnet 也需要特定的委派，但它是委派給 Microsoft.App/environments。

PowerShell

# 定義變數 (假設 VNet 在不同的 RG)
$VNET_RG = "rg-network-shared"
$VNET_NAME = "vnet-pr-stg-twn-01"
$ACA_SUBNET_NAME = "snet-aca-integration" # 建議建立一個新的 Subnet

# 更新 Subnet 委派
az network vnet subnet update `
  --resource-group $VNET_RG `
  --vnet-name $VNET_NAME `
  --name $ACA_SUBNET_NAME `
  --delegations Microsoft.App/environments

第二步：取得 Subnet ID

跨 RG 操作時，直接拿 ID 最安全：

PowerShell

$SUBNET_ID = $(az network vnet subnet show `
  --resource-group $VNET_RG `
  --vnet-name $VNET_NAME `
  --name $ACA_SUBNET_NAME `
  --query id -o tsv)

第三步：建立 Container Apps Environment 並綁定 VNet

這是關鍵步驟。一旦 Environment 建立並綁定 VNet，該環境下所有的 Container Apps 都能直接存取該 VNet 內的資源。

PowerShell

$ENVIRONMENT_NAME = "cae-pr-stg-twn-001"

az containerapp env create `
  --name $ENVIRONMENT_NAME `
  --resource-group $RESOURCE_GROUP `
  --location "taiwannorth" `
  --infrastructure-subnet-id $SUBNET_ID `
  --internal-client-ip-dns-mode "None"  # 如果需要外部存取設為 None，純內網設為 Internal

第四步：部署 Container App 到該環境

PowerShell

az containerapp create `
  --name "my-fast-app" `
  --resource-group $RESOURCE_GROUP `
  --environment $ENVIRONMENT_NAME `
  --image "${ACR_NAME}.azurecr.io/policy-app:v1" `
  --registry-server "${ACR_NAME}.azurecr.io" `
  --target-port 80 `
  --ingress 'external' # 允許外部流量進來

3. 如何存取 VNet 內的資源？

部署完成後，你的 Container App 就像是在 VNet 內的一台機器：

• 透過 IP 存取：你可以直接 ping 或連線 VNet 內 VM 的私有 IP。
• 透過 DNS 存取：如果你 VNet 內有設定 Azure Private DNS Zones，你需要確保 ACA 環境關聯了該 Private DNS，這樣才能解析例如 mydb.privatelink.database.azure.com 這樣的域名。

4. 權限鬼打牆預警 (RBAC)

因為你跨了 Resource Group，且不是 Owner：

1. Network Contributor：你的帳號必須在 VNet RG 擁有這個角色，否則無法將 ACA 環境掛載到該 Subnet。
2. Managed Identity：如果你的 ACA 需要存取 Key Vault 或 SQL (存取權限控管)，建議幫 ACA 開啟 System Assigned Identity。

總結

ACA 的優勢在於一次設定，全家享用。只要把 Environment 塞進 VNet，之後在裡面建立的幾十個微服務就通通都能連內網了。

寫一段建立新 Subnet 的指令

既然要為 Azure Container Apps (ACA) 建立新的 Subnet，我們必須確保該 Subnet 的位址空間不與現有的資源衝突，並且正確設定 委派 (Delegation)。

在跨 Resource Group 的情境下，請執行以下 PowerShell 指令：

1. 定義變數

請根據你的實際環境修改位址範圍（例如 10.0.2.0/24）：

PowerShell

$VNET_RG = "rg-network-shared"         # VNet 所在的 RG
$VNET_NAME = "vnet-pr-stg-twn-01"       # 現有的 VNet 名稱
$NEW_SUBNET_NAME = "snet-aca-infra-01"  # 新 Subnet 的名字
$ADDRESS_PREFIX = "10.0.2.0/24"         # 確保此範圍在 VNet 內且未被使用

2. 建立 Subnet 並設定委派

我們使用 az network vnet subnet create 指令。關鍵在於 --delegations，這會告訴 Azure：「這個網段是給 ACA 環境專用的」。

PowerShell

az network vnet subnet create `
  --resource-group $VNET_RG `
  --vnet-name $VNET_NAME `
  --name $NEW_SUBNET_NAME `
  --address-prefixes $ADDRESS_PREFIX `
  --delegations "Microsoft.App/environments"

3. 取得新 Subnet 的 ID (供後續建立 ACA 環境使用)

建立完成後，建議直接把 ID 存起來，這樣在建立 ACA Environment 時才不會因為名稱解析問題而「鬼打牆」：

PowerShell

$ACA_SUBNET_ID = $(az network vnet subnet show `
  --resource-group $VNET_RG `
  --vnet-name $VNET_NAME `
  --name $NEW_SUBNET_NAME `
  --query id -o tsv)

# 驗證一下有沒有抓到
echo $ACA_SUBNET_ID

執行前的注意事項 (避免再次鬼打牆)

• 位址衝突：請先確認 $ADDRESS_PREFIX 沒有被 VNet 內其他的 Subnet 佔用。你可以執行 az network vnet show -g $VNET_RG -n $VNET_NAME --query "subnets[].addressPrefix" 來查看已使用的網段。
• Subnet 大小：ACA 規定最小必須是 /23 (512 個 IP) 或 /27 (32 個 IP)，具體取決於你的工作負載。對於測試環境，建議至少使用 /24 或 /23，因為 ACA 在升級（Rolling update）或擴展時會消耗大量 IP。
• 權限：雖然你不是 Owner，但只要你在 $VNET_RG 擁有 Network Contributor 角色，就可以成功執行這段指令。

下一步你就可以拿著 $ACA_SUBNET_ID 去執行 az containerapp env create 了。

準備建立環境的完整指令

沒問題！我們直接把 建立 Subnet 到 建立 ACA 環境 的完整流程串起來。這組指令會確保你的 Container Apps 基礎設施能夠正確與 VNet 銜接。

第一階段：建立 Subnet (跨 RG)

請確保你已經定義了之前討論的變數（$VNET_RG, $VNET_NAME 等）。

PowerShell

# 1. 在指定的 VNet RG 下建立專屬 Subnet
az network vnet subnet create `
  --resource-group $VNET_RG `
  --vnet-name $VNET_NAME `
  --name $NEW_SUBNET_NAME `
  --address-prefixes $ADDRESS_PREFIX `
  --delegations "Microsoft.App/environments"

# 2. 獲取該 Subnet 的 Resource ID (這是建立環境的必要參數)
$ACA_SUBNET_ID = $(az network vnet subnet show `
  --resource-group $VNET_RG `
  --vnet-name $VNET_NAME `
  --name $NEW_SUBNET_NAME `
  --query id -o tsv)

第二階段：建立 ACA 環境 (Managed Environment)

這是 ACA 的核心，「環境」決定了容器的網路邊界。

PowerShell

# 定義環境名稱
$ENVIRONMENT_NAME = "cae-pr-stg-twn-001"

# 建立環境並掛載到 VNet ID
az containerapp env create `
  --name $ENVIRONMENT_NAME `
  --resource-group $RESOURCE_GROUP `
  --location "taiwannorth" `
  --infrastructure-subnet-id $ACA_SUBNET_ID `
  --internal-client-ip-dns-mode "None"

專業提示：

• --internal-client-ip-dns-mode "None"：這代表你的 ACA 會有一個公用 IP (External)。如果你希望這是一個純內網（外面完全連不到）的環境，請將此參數改為 Internal。

第三階段：部署第一個 Container App

現在環境已經在 VNet 裡了，我們把你的 App 丟進去測試連通性。

PowerShell

az containerapp create `
  --name "app-pr-stg-twn" `
  --resource-group $RESOURCE_GROUP `
  --environment $ENVIRONMENT_NAME `
  --image "${ACR_NAME}.azurecr.io/policy-app:v1" `
  --registry-server "${ACR_NAME}.azurecr.io" `
  --registry-username $ACR_USERNAME `
  --registry-password $ACR_PASSWORD `
  --target-port 80 `
  --ingress 'external' `
  --query "properties.configuration.ingress.fqdn"

網路架構圖解

這套設定完成後，你的網路架構會長這樣：

驗證 VNet 連通性

部署成功後，你可以進入 ACA 的「主控台 (Console)」或是透過 az containerapp exec 嘗試 ping VNet 內的資源（例如資料庫的 Private IP）：

PowerShell

# 進入容器內部測試
az containerapp exec --name "app-pr-stg-twn" --resource-group $RESOURCE_GROUP --command "ping 10.0.1.5"

避坑指南：關於「位置 (Location)」

ACA 與 VNet 整合時，Region 必須完全一致。

• 如果 VNet 在 Japan East，指令中的 --location 必須填 japaneast。
• 如果 VNet 在 Taiwan North，則填 taiwannorth。

如果跨區建立，az containerapp env create 會報錯並告訴你 Subnet 不在該區域。

答案是, Menu -> Point -> Make Arc

實際測試, 還是 Trimmer 用起來比較順手.

github: https://github.com/jonlabelle/Trimmer

在 Sublime Text 中，除了內建的儲存自動刪除功能，如果你需要更強大的管理工具，像是即時高亮顯示或針對特定區域清理，以下是社群中最推薦的幾個外掛。

TrailingSpaces

這是最受歡迎的選擇。它的主要功能是會用醒目的顏色高亮顯示行尾多餘的空白，讓你一眼就能看到哪裡沒寫乾淨。

1. 安裝方式：透過 Package Control 搜尋 TrailingSpaces。
2. 核心功能：除了高亮顯示，它提供 Delete Trailing Spaces 指令，可以一鍵清除全檔。
3. 進階設定：你可以設定是否要在儲存時自動刪除，或是設定排除目前正在編輯的那一行，避免干擾輸入。

EditorConfig

如果你是團隊開發，這是一個更好的方案。EditorConfig 並非專為刪除空白設計，但它是跨編輯器的格式規範工具。

1. 核心功能：透過專案根目錄的 .editorconfig 設定檔來強制規範。
2. 設定語法：在設定檔中加入 trim_trailing_whitespace = true。
3. 優點：只要專案成員都安裝了這個外掛，不論是用 Sublime、VS Code 還是 WebStorm，儲存時都會遵循相同的空白刪除邏輯，維持代碼的一致性。

如何挑選

如果你只是想要視覺化看到哪些地方有空格，安裝 TrailingSpaces 就對了。如果你在公司工作，為了確保所有同事的格式都一樣，建議直接使用 EditorConfig。若只是單純想保持乾淨且不需要高亮，其實使用 Sublime 內建的 “trim_trailing_white_space_on_save”: true 設定就已經非常足夠。

Error: Did not recognize the following languages: php
Warning: This run of the CodeQL Action does not have permission to access the CodeQL Action API endpoints. This could be because the Action is running on a pull request from a fork. If not, please ensure the workflow has at least the 'security-events: read' permission. Details: Code scanning is not enabled for this repository. Please enable code scanning in the repository settings. - https://docs.github.com/rest

這看起來像是 CodeQL 分析時遇到了兩個常見的障礙：一個是語言設定問題，另一個是 GitHub API 的權限或設定問題。

以下是針對這兩項錯誤的解決方案：

1. 語言錯誤：Did not recognize the following languages: php

問題點： 雖然 CodeQL 支援 PHP，但系統提示無法辨認。

解決方法：

• 檢查大小寫： 在 .github/workflows/codeql.yml 檔案中，請確保語言名稱是全小寫。
• 更新 Action 版本： 確保你使用的是較新的版本（建議使用 @v3）。
• 縮排與語法： 如果有多種語言，請使用列表格式。

YAML

# 範例設定
- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: php  # 確保這裡是小寫

2. 權限與 API 錯誤：does not have permission

問題點： 工作流（Workflow）沒有權限將掃描結果上傳到 GitHub 的安全後台。這通常發生在從 Fork（分叉）出來的 PR，或是權限設定過於嚴格時。

解決方法：

你需要在 YAML 檔案中明確加入 permissions 區塊，賦予工作流寫入安全事件的權力：

YAML

permissions:
  actions: read
  contents: read
  security-events: write  # 這是上傳結果最關鍵的權限

3. 警告：Code scanning is not enabled

問題點： 你的儲存庫（Repository）尚未正式啟用 Code Scanning 功能。

操作步驟：

1. 進入 GitHub 儲存庫的 Settings（設定）。
2. 點擊左側選單的 Code security and analysis。
3. 找到 Code scanning 並點擊 Set up 或確保其為開啟狀態。

[!IMPORTANT]

如果這是私有儲存庫（Private Repo），你必須擁有 GitHub Advanced Security 授權才能使用 CodeQL 的自動掃描功能。

快速檢查清單

請問你這個專案是公開的還是組織內的私有專案呢？這會影響到權限設定的細節。

討論串: Why doesn’t CodeQL support auditing PHP
https://github.com/github/codeql/issues/12376

這是一個很常見的誤解。簡單來說：CodeQL 絕對支援 PHP，但在 GitHub Action 的某些特定版本或環境下，可能會因為「配置方式」導致它找不到 PHP。

關於你提到的 issue (#12376) 以及相關的討論，這裡有幾個核心重點幫助你理解：

1. CodeQL 確實支援 PHP

PHP 是 CodeQL 官方支援的語言之一（包括分析 SQL 注入、跨站腳本 XSS 等漏洞）。你可以從官方文件中看到 PHP 始終在支援清單中。

2. 為什麼會出現 “Did not recognize php” 的錯誤？

在該 issue 和類似案例中，通常是因為以下兩個原因：

• 版本相容性 (Action Version)： 如果你使用的 github/codeql-action 版本太舊，或者內含的 CodeQL CLI 版本不匹配，可能會導致語言包加載失敗。
• 預設套件包 (Standard Bundles)：CodeQL 在執行時會下載一個包含所有語言規則的「套件包 (Bundle)」。如果下載過程中出錯，或是你指定的分析器路徑不對，就會報出找不到語言的錯誤。
• 大小寫問題：CodeQL 對設定檔非常敏感，必須確保是全小寫的 php。

3. 如何解決這個問題？

根據目前的最佳實踐，請檢查並修正你的 .github/workflows/codeql.yml：

A. 更新 Action 版本（最重要）

確保你使用的是 v3（目前的主流版本）：

YAML

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: php

B. 手動指定 CodeQL 套件來源（如果問題持續）

有時候 GitHub 的託管執行器（Runner）快取了壞掉的 CodeQL 版本。你可以嘗試強制它使用最新的版本：

YAML

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: php
    tools: latest # 強制下載最新版工具

4. 針對你提到的權限錯誤（補充）

你之前提到的第二個錯誤 Warning: This run of the CodeQL Action does not have permission... 其實才是主因。

當 CodeQL 因為權限不足無法從 GitHub API 獲取配置或下載必要的語言組件時，它可能會退回到一個「空狀態」，然後報錯說它「不認識 php」。

請務必檢查：

• 你的 Repository 設置中：Settings > Code security and analysis > Code scanning 是否已啟動？
• 如果這是 Fork 過來的專案，預設是不能執行 CodeQL 並回傳結果的（為了安全）。你必須在 PR 頁面手動核准執行，或者在該 Fork 倉庫的設定中開啟 Actions 權限。

總結

CodeQL 支援 PHP。 你看到的錯誤通常不是因為「不支援」，而是因為 權限被阻擋 或 Action 版本過舊 導致 CodeQL 無法正確加載 PHP 的分析模組。請嘗試將 Action 更新至 v3 並在 YAML 中加入 permissions: security-events: write。

PHP is not supported by CodeQL. What should we do with codeql-analysis.yml?

雖然 CodeQL 目前不支援 PHP，但這並不代表 codeql-analysis.yml 就完全沒有用處。如果你的專案除了 PHP 之外，還包含 JavaScript、TypeScript、HTML 或 CSS 等前端程式碼，CodeQL 依然可以掃描這些語言中的安全漏洞。建議先確認專案的語言組成，如果確實只有純 PHP 程式碼，直接移除這個檔案是合理的選擇，這樣可以避免 CI 執行無意義的掃描，節省系統資源。

如果專案包含前端程式碼，你可以修改設定檔，將語言限制在 CodeQL 支援的範圍內。如果你決定移除它，第一選項提到的 PHPStan 確實已經處理了大部分的靜態分析任務。不過要注意的是，PHPStan 主要專注於型別檢查和邏輯錯誤，而 CodeQL 類型的工具通常更偏向安全性漏洞掃描（如 SQL 注入）。如果你對安全性有高度要求，可以考慮第二選項，導入像 Snyk 或 Psalm 的安全分析外掛，來補足安全性掃描的空缺。

若選擇移除，請直接刪除 .github/workflows/codeql-analysis.yml。若專案未來計畫引入其他語言，則可以考慮暫時停用而非刪除。總結來說，若專案結構單一且 PHPStan 已能滿足開發需求，採取第一選項移除檔案是最簡潔的做法。

這兩款工具在 PHP 社群都非常知名，但定位和收費模式完全不同。簡單來說，Psalm 適合預算有限、追求深度程式碼檢查的專案；Snyk 則適合企業級開發，需要更完整的安全性掃描生態。

Psalm 安全分析

Psalm 本身是完全免費且開源的靜態分析工具。它最強大的地方在於 Taint Analysis（汙點分析），可以追蹤不受信任的輸入（如 $_GET）是否流向了危險的函數（如 query()），從而檢測 SQL 注入或 XSS。

安裝步驟

如果你已經有專案，可以使用 Composer 進行安裝：

1. 安裝主程式：composer require --dev vimeo/psalm
2. 初始化設定：./vendor/bin/psalm --init這會生成一個 psalm.xml 設定檔。
3. 啟用安全分析：在 psalm.xml 中確保啟用了 taintAnalysis，或是直接在執行時加入參數：./vendor/bin/psalm --taint-analysis
4. 安裝框架外掛（選配）：如果你使用 Laravel 或 Symfony，建議安裝專屬外掛，分析會更準確：composer require --dev psalm/plugin-laravel./vendor/bin/psalm-plugin enable psalm/plugin-laravel

Snyk 安全掃描

Snyk 是一個商業產品。對於開源專案或個人小規模使用，它提供免費額度（Free Plan），但對於企業或需要大量掃描、進階合規報告的團隊，則需要付費。2026 年的 Team 版本起跳價大約在每位開發者每月 50 美元左右。

安裝步驟

Snyk 通常是透過 CLI 或直接整合到 GitHub 工作流中。

1. 安裝 Snyk CLI：在本地或 CI 環境執行：npm install -g snyk
2. 驗證身份：snyk auth這會跳轉到瀏覽器讓你登入帳號。
3. 進行掃描：在專案根目錄執行以下指令來檢查依賴套件與程式碼漏洞：snyk test
4. GitHub 工作流整合：你可以在 .github/workflows 中建立 snyk.yml，使用官方提供的 Action：YAMLsteps: - uses: actions/checkout@v4 - uses: snyk/actions/php@master env: SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

該選哪一個

• 如果你想要不花一毛錢就達到極致的程式碼安全檢查，選 Psalm。它對 PHP 的理解非常深，但設定上會比較囉嗦。
• 如果你希望有漂亮的儀表板、自動掃描開源套件（SCA）的漏洞，且不介意免費額度的限制，選 Snyk。它的強項在於全面性的漏洞資料庫。

解決 Composer 找不到的問題

如果你是在 Windows 環境下，最簡單的解決方法是去 Composer 官網下載並執行 Composer-Setup.exe 安裝檔。

傳送門: https://getcomposer.org/download/

安裝過程中它會自動尋找你的 php.exe 路徑，並幫你把執行命令設定好。安裝完成後，務必重新啟動你的終端機（如 CMD 或 PowerShell），這樣設定才會生效。

如果你確定已經安裝過，請檢查 PHP 的安裝路徑是否已經加入到系統環境變數中。你可以在終端機輸入 php -v 來確認。如果連 php 都不被辨認，那代表你必須先搞定 PHP 的環境。

關於在本機檢查

是的，當你執行 composer require --dev vimeo/psalm 時，這是在你的開發本機進行操作。

這行指令的意思是將 Psalm 下載到你專案資料夾裡的 vendor 目錄中。--dev 參數表示這個工具只在開發環境使用，實際把程式碼上傳到正式伺服器時，不會包含這些測試工具。

在本機檢查的好處是，你可以在程式碼還沒上傳到 GitHub 或伺服器之前，就先發現潛在的安全性問題。這通常被稱為「左移測試」（Shift-Left Testing），也就是在開發初期就介入檢查。

執行本機檢查的流程

當你解決了 Composer 的問題後，在本機操作的完整流程如下：

安裝： 執行

composer require --dev vimeo/psalm

初始化： 執行

./vendor/bin/psalm --init

這會在你的專案裡產生一個設定檔，讓 Psalm 知道要檢查哪些資料夾。

執行掃描： 執行

./vendor/bin/psalm

它會開始掃描你的程式碼並在終端機顯示錯誤報告。

如果你覺得在本機手動執行很麻煩，通常我們會把這套流程整合進 VS Code 等編輯器的外掛中，讓你邊寫程式時，編輯器就直接畫紅線提醒你哪裡可能有安全性漏洞。

為什麼這比在 GitHub 上檢查快

在本機執行檢查的反應速度最快。如果你只靠 GitHub Actions（也就是你原本提到的 codeql-analysis.yml 所在的環境）來檢查，你必須先 commit 並 push 程式碼，等待雲端主機啟動，然後才能看到結果。在本機跑 Psalm 通常只需要幾秒鐘，能節省大量的等待時間。

● CodeQL 完全不支援 PHP，這也是我們移除 codeql-analysis.yml 的原因。

支援的語言只有：C/C++、C#、Go、Java/Kotlin、JavaScript/TypeScript、Python、Ruby、Swift。

針對 PHP 的替代方案：

┌────────────────────────────────┬───────────────────────────────────┐
│ 工具 │ 用途 │
├────────────────────────────────┼───────────────────────────────────┤
│ Psalm (--taint-analysis) │ 資安漏洞（SQL injection、XSS 等） │
├────────────────────────────────┼───────────────────────────────────┤
│ PHPStan │ 型別錯誤、靜態分析 │
├────────────────────────────────┼───────────────────────────────────┤
│ PHP CodeSniffer │ 程式碼風格（PSR-12） │
├────────────────────────────────┼───────────────────────────────────┤
│ composer audit │ 相依套件已知漏洞 │
└────────────────────────────────┴───────────────────────────────────┘

這些都能在本機直接執行，速度比 GitHub Actions 快很多。

本文目錄

1. 事情是這樣開始的
2. 發生了什麼事：文章被複製三次
3. 根本原因大揭秘（共三個，一個比一個妙）
4. 怎麼修：三個外科手術等級的改法
5. 血淚教訓：寫 AI Prompt 規格時你一定要知道的事
6. 懶人包 TL;DR

事情是這樣開始的

想像一下你打開了一個剛生成的 keyword.md，然後你看到這個：

# 遠端工作的真實面貌

遠端工作聽起來很美好，穿著睡衣開會、貓咪在旁邊陪...

（此處省略 1200 字精彩文章）

---

# 遠端工作的真實面貌

遠端工作聽起來很美好，穿著睡衣開會、貓咪在旁邊陪...

（此處又省略 1200 字一模一樣的文章）

---

# 遠端工作的真實面貌

（你沒看錯，還有第三份）

恭喜你，你的 AI 助理今天特別勤勞，把同一篇文章幫你寫了三遍。 這不是功能，這是 Bug。而且是那種「看起來好像在工作」的 Bug， 最讓人崩潰。

這是我們在開發 blog-pro-max（一套把 Skill 注入到 18 種 AI 平台的部落格寫作工具）時， 在 Gemini CLI 的 Skill Mode 上踩到的真實坑。這篇文章就是完整的偵錯過程紀錄， 希望你看完之後，可以省下我花掉的那幾個小時。

發生了什麼事：文章被複製三次

系統架構快速說明

blog-pro-max 的運作方式是這樣的：

1. 用 blogpro init --ai gemini 把一個 SKILL.md 注入到 Gemini CLI
2. Gemini CLI 讀取 SKILL.md，知道自己有「寫部落格文章」的能力
3. 使用者輸入指令，Gemini CLI 依照 SKILL.md 的規格執行：生成文章、做分析、存檔

理論上，最終應該輸出三個乾淨的檔案：

實際上，keyword.md 裡面長這樣：

實際輸出（節錄）

文章本文 × 1 → 邏輯審稿報告（包含再次輸出的文章本文）× 1 → 結構審稿報告（又包含文章本文）× 1 → …

最後 keyword.md 的大小：應有 3KB，實際有 27KB。

根本原因大揭秘（共三個，一個比一個妙）

找 Bug 的第一步，當然是把程式碼放在眼前盯著看，然後說「這不可能啊」。 讓我們來逐一拆解。

Bug #1

LLM 每產一段分析就 write_file 一次

SKILL.md 的 LLM-only 模式指示 Gemini CLI：「執行全科檢查、標題建議、封面提示詞、時事趨勢……」 沒有明確說什麼時候存檔。於是 Gemini CLI 很有 initiative 地選擇： 每產出一段分析，就立刻呼叫 write_file 存一次。

問題是：LLM 在呼叫 write_file 的時候，通常不是「附加模式（append）」， 而是重新生成整個檔案內容。它會把整個對話脈絡（包含剛才輸出的文章本文） 一起寫進去。然後下一段分析完成，又重新寫一次，文章本文又出現一次。

執行 12 段分析 = 文章本文出現 13 次（第一次正常存，後面 12 次每次都夾帶一份）。 恭喜你，獲得免費的 ×13 文章。

核心觀念

LLM 的 write_file 工具呼叫是覆寫（overwrite），不是 append。 每次呼叫都會寫入你在 prompt context 裡看到的「目前完整內容」。 你以為在附加，AI 其實在複製貼上。

Bug #2

LLM-only 區塊裡偷偷藏了腳本指令（邏輯矛盾）

這個 Bug 讓我看了三遍才看懂。在 SKILL.md 的「不具備執行腳本能力」區塊裡， 步驟 5 有這樣一行：

- 若 AI 具備執行腳本能力，執行：
    python output_md2html.py output/keyword.md output/keyword.html \
      --analysis output/keyword_analysis.md

等等……這在「不具備腳本能力」的區塊裡，說的是「若具備腳本能力」？？

這是某次重構時的遺留程式碼（我知道，不要笑）。 Gemini CLI 解讀這個邏輯的方式是： 「我是 Gemini CLI，我可以執行腳本，所以我要走腳本路徑。 但我現在也在 LLM 模式裡，所以我也要走 LLM 路徑。」 於是兩條路都走了，存了兩次。

這是什麼感覺

就像告示牌上寫：「如果你會開車，請停車。如果你不會開車，請停車。如果你會開車，請繼續開。」 然後有個人在十字路口停了三次。

Bug #3

腳本執行失敗時靜默回退到 LLM 模式

content_research.py 需要 GITHUB_TOKEN 或 OPENAI_API_KEY 才能呼叫 LLM。如果這些 key 沒設定，腳本會直接 crash。

但 SKILL.md 沒有說腳本失敗時要怎麼辦。於是 Gemini CLI 很有 can-do 精神地說： 「腳本不行沒關係，我自己用 LLM 生成！」

然後就悲劇了：腳本已經把文章部分寫入了 keyword.md（或者創建了空檔案）， Gemini CLI 的 LLM 又重新生成一遍，疊加進去。 最後你打開 keyword.md，看到的是腳本的殘骸 + LLM 的全文，拼在一起。

沉默的失敗是最可怕的

明確的錯誤訊息是你的朋友。靜默回退是你最危險的敵人。 永遠要明確指定「失敗時應該做什麼」，尤其是當執行結果會寫入檔案的時候。

怎麼修：三個外科手術等級的改法

找到病因之後，修法其實相當直接。以下是每個 Bug 對應的修法。

Fix #1

明確指定「全部完成後一次性寫入」

在 SKILL.md 的 LLM-only 存檔規則前，加入明確的防護說明：

舊的（含糊）

自動執行所有分析：全科檢查、標題建議……

儲存規則：
– output/keyword.md：僅存文章本文
– output/keyword_analysis.md：所有分析結果
– output/keyword.html：合併

新的（明確）

執行順序（所有分析在記憶體中累積）：
全科檢查 → 標題 → 封面 → 時事趨勢 → …

存檔規則（必須嚴格遵守）：
– keyword.md：只呼叫 write_file 一次，之後絕對不再修改
– keyword_analysis.md：全部完成後才 write_file 一次
– 禁止對同一個檔案呼叫多次 write_file

關鍵字是「記憶體中累積」和「一次性寫入」。 給 LLM 的指令越明確，它越不會自由發揮。

Fix #2

把錯誤嵌套的腳本指令移出 LLM-only 區塊

把那行混入 LLM-only 區塊的 output_md2html.py 指令直接刪除。 LLM-only 模式就讓 LLM 自己生成 HTML，不要夾帶腳本指令。

改完之後，兩個區塊變得清清楚楚、互不干擾：

/* 具備腳本能力 */
→ 執行 content_research.py（腳本自己搞定一切）
→ 回報結果

/* 不具備腳本能力（純 LLM） */
→ 生成文章 + 執行所有分析（全在 memory）
→ 一次性寫三個檔案
→ HTML 直接用 LLM 合併兩個 .md 的內容輸出

Fix #3

在腳本模式加「失敗就停，別偷偷改模式」

在「具備腳本能力」的步驟 5 後面，加上明確的失敗處理指令：

> ⚠ 若腳本執行失敗（例如缺少 API 金鑰或環境問題），
> 請直接顯示錯誤訊息並停止。
> 不要改用 LLM 模式重新生成文章，
> 以避免與腳本已寫入的部分內容重疊。

就這一段話。十秒鐘加進去的文字，省了好幾次「為什麼文章又重複了」的困惑。

血淚教訓：寫 AI Prompt 規格時你一定要知道的事

Lesson 1：LLM 的 write_file ≠ append

這是最根本的認知差距。你可能以為 LLM 在「附加分析到 .md 檔」， 但它實際上是「重新生成完整的 .md 內容後覆寫」。 在任何涉及分次寫入的場景，都必須明確指定「collect → write once」的順序。

Lesson 2：Prompt 的分支邏輯要互斥且完整

if A → do X，if not A → do Y。這兩個分支要確保：

• 互斥（進了 A 就不能再進 not-A 的分支）
• 每個分支裡只有屬於自己的指令（不要偷渡對方的內容）
• 都有失敗處理（明確說失敗時要做什麼，不要讓 AI 自由心證）

人寫 if/else 都會 bug，更何況是自然語言寫給 LLM 的條件分支。

Lesson 3：靜默回退（Silent Fallback）是所有 Bug 的老爸

在 AI agent 系統裡，「我做不到就換個方式做」聽起來很聰明， 但如果沒有明確說「換個方式前要先清除之前的影響」， 就會出現兩個執行路徑同時留下痕跡的混亂狀態。

規則很簡單：可以 fallback，但必須先 cleanup；或者根本禁止 fallback，直接 fail-fast。 後者在寫入檔案的場景通常更安全。

Lesson 4：Prompt Spec 也要 Code Review

SKILL.md 裡的那個「LLM-only 區塊藏著腳本指令」的 Bug， 是重構時從其他地方複製過來的殘留程式碼。

普通程式碼有 linter、有 type checker、有 unit test。 Prompt 規格文件什麼都沒有。 所以在你覺得「這個 prompt 寫好了」的時候，最好把它當成 code 一樣做一次 邏輯審查：每個分支都走一遍，看看有沒有矛盾的指令。

Lesson 5：「應該很直觀」是 Bug 最常見的藏身地

「LLM 應該知道只要寫一次吧？」 「腳本失敗了應該會跳錯吧？」 「分支應該不會混在一起吧？」

以上三句話，分別對應了本文的三個 Bug。 凡是「應該」的地方，就是你需要寫明確指令的地方。 在人機協作的系統裡，不要假設任何「顯而易見」的行為。

懶人包 TL;DR

修完之後的感覺

打開 keyword.md，看到乾淨的文章本文，只有文章本文，沒有重複， 分析全部在 keyword_analysis.md，HTML 合併得漂漂亮亮。 這種「終於正常了」的快感，大概是所有開發者共同的語言。

如果你也在開發類似的 AI agent 系統，希望這篇文章能幫你少踩幾個坑。 如果你踩到的坑比我還奇特，歡迎留言分享，讓大家一起開心（或一起哭）。

這是在執行 xcopy 指令時，因為嘗試複製 .git 資料夾內的系統檔案或正在被使用的檔案，導致權限不足或檔案被鎖定而中斷。當你使用 /s 參數時，xcopy 會連同隱藏的設定檔一起搬移，但 Git 的內部資料庫通常不建議這樣直接複製。

解決這個問題最快的方法是排除 .git 資料夾，因為你通常只需要程式碼檔案，而不需要把舊的 Git 紀錄也強制蓋過去。你可以改用 robocopy 指令，它比 xcopy 更強大，且可以輕鬆排除特定目錄。

請嘗試執行以下指令：

robocopy "c:\max\play\blog-pro-max" "c:\max\git\blog-pro-max" /s /e /xd .git

這個指令的原理是將來源路徑的所有子目錄與檔案複製到目標路徑，但透過 /xd 參數把 .git 資料夾排除在外。這樣就能避免觸碰那些會導致存取被拒的隱藏系統檔案，同時確保你的程式碼與文件能順利完成同步。

如果你堅持要連同 Git 紀錄一起複製，請先確認沒有任何程式（例如 VS Code 或 Git GUI）正在開啟該專案，並嘗試以系統管理員身分執行命令提示字元。不過實務上，使用 robocopy 排除不必要的元資料是比較穩健的做法。

之前產生的 SSH 金鑰有設定密碼鎖。雖然這比沒設密碼安全，但每次都要輸入確實很麻煩。如果你不想重新產生金鑰，有兩個方法可以解決。

使用 ssh-agent 自動管理

這是最推薦的做法。你可以讓系統在背景跑一個代理程式，幫你記住解鎖後的金鑰。只要在 WSL 終端機執行這兩行指令：

eval $(ssh-agent -s)
ssh-add ~/.ssh/id_rsa_personal

執行第二行時，輸入最後一次密碼。之後只要這個視窗沒關掉，再次 push 就不會再問你密碼。

如果你希望每次開啟 WSL 都自動生效，可以把這兩行指令加到 ~/.bashrc 檔案的最末端。這樣每天第一次開機輸入一次，之後整天都不用再打。

移除金鑰本身的密碼

如果你覺得在私有電腦上不需要這層保護，也可以直接把金鑰的密碼拿掉。執行這行指令：

ssh-keygen -p -f ~/.ssh/id_rsa_personal

系統會先要求你輸入舊密碼。接著會問你新的密碼，這時直接按兩次 Enter 留白。這樣這組金鑰就會變成無密碼狀態，以後執行 git push 就會直接通過。

確認設定是否正確

處理完密碼後，你可以測試一下連線是否正常。輸入：

ssh -T git@github.com -i ~/.ssh/id_rsa_personal

如果看到 Hi 帳號名！You’ve successfully authenticated，就代表搞定了。以後不管 Windows 那邊登入哪個帳號，WSL 這邊都會走你這組專屬的 SSH 金鑰。

如果你使用的是 zsh，要把設定寫在 ~/.zshrc 這個檔案裡。

修改設定檔

你可以使用 nano 或 vim 來編輯：

nano ~/.zshrc

把下面這段程式碼貼到檔案的最末端：

Bash

if [ -z "$SSH_AUTH_SOCK" ]; then
   eval $(ssh-agent -s)
   ssh-add ~/.ssh/id_rsa_personal
fi

存檔離開後，執行 source ~/.zshrc 讓設定立即生效。這樣你下次開啟新的 zsh 視窗時，系統就會自動啟動代理並載入你的金鑰。

使用 oh-my-zsh 插件

如果你有安裝 oh-my-zsh，其實有一個更優雅的插件做法。在 ~/.zshrc 找到 plugins=(…) 這行，把 ssh-agent 加進去：

plugins=(git ssh-agent)

接著在下面補上一行設定，指定要自動載入的金鑰名稱：

zstyle :omni:plugins:ssh-agent identities id_rsa_personal

這樣它會在你開啟終端機時自動處理一切，不用自己寫 shell script。

解決重複啟動問題

要注意的是，如果直接在設定檔寫 eval，每次開新視窗都會產生一個新的 ssh-agent 處理程序。如果你發現系統變慢，或是用 ps 指令看到一堆 ssh-agent，建議使用上面提到的 if 判斷式，或是安裝 keychain 這個套件來管理。

keychain 會幫你找現有的代理程序，確保整個系統只跑一個 ssh-agent。這對於習慣開多個分頁的人來說，是比較乾淨的做法。

關於 Keychain

keychain 是一個用來管理 ssh-agent 的工具。它的好處是能讓所有開啟的終端機視窗共用同一個 ssh-agent。如果不使用它，你每開一個新的 zsh 分頁，系統可能就會跑一個新的 ssh-agent 程式，久了會變得很亂。

keychain 會在背景記住你解鎖過的金鑰。只要你在第一次登入時輸入過一次密碼，之後不管是重開分頁還是執行 git push，它都不會再煩你。

安裝方式

在 Ubuntu 或 WSL (Ubuntu) 環境下，安裝非常簡單。直接輸入這行指令：

sudo apt update && sudo apt install keychain

安裝完後，它還不會自動運作，需要去修改你的 zsh 設定檔。

設定 zsh 自動執行

你需要把啟動指令加進 ~/.zshrc。請編輯該檔案：

nano ~/.zshrc

在檔案最後面加上這兩行程式碼：

Bash

/usr/bin/keychain --nogui ~/.ssh/id_rsa_personal
source ~/.keychain/$HOST-sh

第一行是叫 keychain 去管理你的那把金鑰。第二行則是載入相關的環境變數，讓目前的 zsh 知道要去哪裡找已經解鎖的金鑰。

實際使用效果

設定完成後，執行 source ~/.zshrc 或是重開視窗。這時候系統會最後一次詢問你金鑰的密碼。

輸入完畢後，這把金鑰就會一直保持在解鎖狀態。就算你開了十個 zsh 視窗，也都只需要輸入那一次密碼。這對頻繁使用 git push 的開發者來說，是最省心也兼顧安全的方法。

在 Windows CMD 環境下，Git 每次 push 都要求輸入密碼鎖，通常是因為 SSH Agent 沒有在背景執行，或是金鑰沒有被正確載入。以下提供兩個主要的解決方案。

使用 Windows 內建的 OpenSSH 服務

這是最推薦的做法，因為它可以讓 SSH Agent 在開機時自動啟動，並持久化儲存你的金鑰密碼。

以管理員身分開啟 PowerShell，執行以下指令將 OpenSSH Authentication Agent 服務設定為自動啟動

Set-Service -Name ssh-agent -StartupType AutomaticStart-Service ssh-agent

回到一般的 CMD 視窗，將你的私鑰加入 Agent。假設你的金鑰路徑是預設值：

ssh-add %USERPROFILE%\.ssh\id_rsa

執行後系統會要求你輸入最後一次密碼鎖。之後只要服務維持執行狀態，重開 CMD 也不需要再輸入密碼。

執行上述指令, 錯誤訊息:

Error connecting to agent: No such file or directory

這個錯誤通常是因為 CMD 無法識別 %USERPROFILE% 後接續的路徑格式，或是 ssh-agent 服務雖然啟動了，但目前的視窗環境變數還沒有對接上。你可以依照以下步驟排查並修正。

修正路徑格式與環境變數

在 CMD 中，路徑的分隔符號與變數引用非常嚴格。請嘗試手動補上反斜線，並加上雙引號確保路徑正確：

ssh-add "%USERPROFILE%\.ssh\id_rsa"

如果依然顯示無法連線到 Agent，請在同一個 CMD 視窗內執行以下指令，手動啟動 Agent 並設定環境變數：

for /f "tokens=1-2 delims==;" %a in ('ssh-agent -s') do set %a=%b

執行完畢後，再次嘗試執行 ssh-add 指令。

確認 SSH 服務執行狀態

如果手動啟動有效，但每次開新視窗都要重來，代表系統服務沒有正確常駐。請再次確認服務狀態：

1. 按下 Win + R 鍵，輸入 services.msc 並執行。
2. 找到 OpenSSH Authentication Agent。
3. 確認狀態為 正在執行，且啟動類型為 自動。

結果是服務被停用, 啟用就好了.

檢查 GIT_SSH 環境變數

有時候安裝 Git 時會內建自家的 SSH 套件，這會干擾系統內建的 ssh-add。請檢查你的環境變數中是否有名為 GIT_SSH 的變數。如果有，請將它刪除，讓 Git 預設使用系統路徑 C:\Windows\System32\OpenSSH\ssh.exe。

另外，請確認你的 .ssh 資料夾內確實存在 id_rsa 這個檔案。你可以輸入 dir %USERPROFILE%.ssh 來查看檔案清單。如果你的金鑰檔名不是 id_rsa (例如是 id_ed25519)，請將指令中的檔名更換為正確的名稱。

設定 Git 使用內建的 SSH 工具

有時候 Git 會使用自己打包的 SSH 工具而不是 Windows 系統路徑下的工具，這會導致兩者金鑰紀錄不互通。你可以強制 Git 指向系統的 SSH 路徑：

git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe

修改金鑰設定移除密碼鎖

如果你覺得維護 Agent 服務太麻煩，且確認電腦環境安全，也可以選擇直接移除私鑰的密碼鎖。

執行以下指令：

ssh-keygen -p -f %USERPROFILE%.ssh\id_rsa

系統會先要求輸入舊密碼，當詢問新密碼時直接按兩次 Enter 留白。這樣該金鑰就會變成無密碼狀態，之後任何 Git 操作都不會再跳出輸入提示。不過請注意，這會降低金鑰外洩時的安全性。

很多人為了方便管理，會把預設的 SSH 私鑰檔名從 id_rsa 改成更有辨識度的名稱，例如 id_rsa_personal。沒想到改完名後，原本可以秒連的伺服器突然都跳出權限錯誤。這不是因為金鑰失效，而是因為 SSH 客戶端「迷路」了。

為什麼改名後會連線失敗？

SSH 客戶端在發起連線時，預設只會自動尋找幾個固定名稱的檔案，像是 id_rsa、id_ecdsa 或 id_ed25519。一旦你將檔案改名，原本依賴自動偵測的機制就會找不到對應的私鑰，導致連線被拒絕。

要修復這個問題，你不需要把檔名改回去，而是要學會使用 SSH 的「地圖」——也就是 config 檔案。

使用 Config 建立通用對應規則

你可以透過編輯 ~/.ssh/config 檔案，告訴 SSH 客戶端你的金鑰躲在哪裡。請在該檔案中加入以下設定：

Host *
  IdentityFile ~/.ssh/id_rsa_personal

這段設定的意思是：無論連線到哪一個網域（Host *），如果找不到特定的金鑰，就統一嘗試使用這把 id_rsa_personal。這樣一來，原本受影響的站點就能恢復正常連線。

舉例：這就像你在公司設定了一個「預設聯絡人」，不管客戶從哪裡打來，只要沒人接，電話就會自動轉給這個人。

多把金鑰的精確分流做法

如果你手邊有多把金鑰分別對應不同的帳號（例如公司用與私人用），建議採取更精確的分流設定。例如，針對 GitHub 使用特定的金鑰，而其他站點則使用另一把：

Host github.com
HostName github.com
IdentityFile ~/.ssh/id_rsa_personal

Host *
IdentityFile ~/.ssh/id_rsa_other

透過這種方式，SSH 就會根據你連線的目標，自動選取正確的「鑰匙」開門，再也不用手動指定。

連線診斷與最後提醒

設定好之後，你可以使用 ssh -v 加上目標網域（例如 ssh -v git@github.com）來觀察連線過程。在輸出的冗長資訊中，你會看到 SSH 開始嘗試載入你指定的 IdentityFile。

在 Linux 或 WSL 的環境下，系統對金鑰檔案的安全性要求很高。如果你改名後檔案的權限跑掉了，系統會覺得這把鑰匙太危險而拒絕使用。

請檢查你的金鑰權限是否維持在 600（這代表只有你自己可以讀寫）。你可以輸入指令檢查，如果權限不對，連線是絕對不會成功的。

如果你平常有在使用 ssh-agent（這是一個幫你在背景管理鑰匙、讓你不用每次都輸入密碼的小工具），光是改掉檔案名稱是不夠的。

因為管理員的記憶中存的還是舊的名字。改名後，請記得執行 ssh-add ~/.ssh/id_rsa_personal（這裡的檔名請換成你修改後的名字），手動將新檔名的金鑰重新載入到記憶體中，這樣連線時系統才抓得到正確的鑰匙。

結語

管理 SSH 金鑰不該是一件痛苦的事。透過 ~/.ssh/config 檔案，我們不僅能自由為金鑰命名，還能優雅地處理多個帳號的分流連線。下次遇到連線問題時，先檢查一下你的「地圖」(config)設定是否正確吧！

Ubuntu 或 Debian 系列的 WSL 中，建議使用官方的套件庫進行安裝。

安裝步驟

你可以依序執行下列指令來完成安裝。這會下載 GitHub 的官方金鑰並將套件來源加入你的清單中。

type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh -y

驗證安裝

安裝完成後，請輸入指令確認版本。

gh --version

如果畫面正確顯示版本資訊，代表安裝成功。

登入帳號

在使用 gh 建立 release 之前，你必須先進行授權，否則會因為權限不足被拒絕。請執行以下指令並依照畫面提示操作。

gh auth login

通常建議選擇透過瀏覽器 (web browser) 登入，它會跳出一個視窗要求你輸入 GitHub 帳號密碼，或是給你一組 code 貼上。

排除路徑問題

如果你確定已經安裝過，但 zsh 仍然找不到，可以嘗試執行 source ~/.zshrc 重新讀取設定檔。如果是透過 Linuxbrew 安裝的，請檢查 /home/linuxbrew/.linuxbrew/bin 是否在你的 PATH 變數中。你可以輸入 echo $PATH 來檢查目前的環境變數路徑。

在 Windows 上安裝 GitHub CLI (gh) 有幾種常見且快速的方法。根據你是否有使用套件管理員，可以選擇最適合你的方式。

使用 Winget 安裝

這是 Windows 10 與 11 內建的推薦方式，不需要額外下載安裝檔，直接在 PowerShell 或命令提示字元 (CMD) 執行即可。

winget install --id GitHub.cli

使用 Scoop 安裝

如果你有在使用 Scoop 這個套件管理工具，可以用以下指令安裝。Scoop 通常會處理好所有路徑設定，對開發者非常友善。

scoop install gh

使用 Chocolatey 安裝

如果你習慣使用 Chocolatey，請執行。

choco install gh

使用安裝程式 (MSI)

如果你偏好傳統的點擊安裝方式，可以依照以下步驟操作。

1. 前往 GitHub CLI 的官方 Release 頁面。
2. 下載檔名結尾為 .msi 的檔案 (例如 gh_2.x.x_windows_amd64.msi)。
3. 執行該檔案並一路點擊下一步直到完成。

驗證與登入

安裝完成後，請務必重新啟動你的終端機 (PowerShell、CMD 或 Windows Terminal)，然後執行指令檢查。

gh --version

確認能讀取到版本後，執行登入指令。

gh auth login

依照畫面提示選擇 GitHub.com，並使用瀏覽器進行授權即可完成設定。如果你之後要在 WSL 裡面使用，記得 WSL 與 Windows 的環境是分開的，需要在 WSL 內再安裝一次。

使用 GitHub CLI (gh) 自動化處理 tag 與 release 非常方便，這可以讓你在不離開終端機的情況下完成原本需要在網頁上點擊的操作。首先請確保你已經安裝 gh 並完成登入。

新增 Tag

雖然 gh 主要用於處理 GitHub 特有的功能，但新增 tag 通常建議直接使用 git 指令，再搭配 gh 進行後續操作。你可以先在本地建立標籤並推送到遠端。

git tag 1.0.0
git push origin 1.0.0

如果你想完全自動化，可以將這些指令寫在腳本中。

建立 Release

一旦 tag 存在於 GitHub 遠端，你就可以使用 gh release create 指令。最基本的用法是指定標籤名稱。

gh release create 1.0.0

如果你希望在建立時直接指定標題和說明內容，可以使用參數。

gh release create 1.0.0 --title "正式版更新" --notes "修正了已知錯誤並提升效能"

自動化與檔案上傳

在自動化流程中，你可能需要上傳編譯好的二進位檔或壓縮包，這時候只要在指令最後加上檔案路徑即可。

gh release create 1.0.0 ./dist/app.zip --generate-notes

加上 –generate-notes 參數會讓 GitHub 自動根據兩次 release 之間的 commit 紀錄產生說明內容。如果你在 CI/CD 環境中使用，記得確保環境變數中包含有效的 GITHUB_TOKEN。

常用參數說明

如果你想要建立的是預發佈版本，可以加上 –prerelease 參數。如果你想先建立草稿而不直接發佈，可以使用 –draft。

gh release create 1.0.1 --draft --title "開發中版本"

這組指令能幫你快速整合進 shell script 或 GitHub Actions，實現全自動的版號管理。