859 背景自動更新859 背景自動更新
860</h4>860</h4>
861 861
862根據預設，背景重新整理會停用 git 認證助手，當它檢查 marketplace 的遠端以尋找新提交時，因此檢查無法對私人儲存庫進行 HTTPS 驗證，即使已配置助手。SSH 遠端不受影響：載入在 `ssh-agent` 中的金鑰會以與您執行的命令相同的方式驗證背景檢查。862背景重新整理會檢查 marketplace 的遠端以尋找新提交，使用您配置的 git 認證助手，與您執行的命令相同。對於 SSH 遠端，載入在 `ssh-agent` 中的金鑰會驗證檢查。Claude Code 以非互動方式執行檢查：它關閉 git 的終端提示和 askpass 程式，並告訴認證助手不要提示。檢查是否可以透過 HTTPS 驗證私人儲存庫取決於您的助手：
863 863
864當檢查找到新提交，或因為無法到達或驗證遠端而失敗時，Claude Code 會重新複製 marketplace 並交換新複製。如果該複製失敗，現有簽出會保留在原位。重新複製確實會使用您儲存的 git 認證，但它可能會在大型儲存庫上[逾時](#git-operations-time-out)，因此私人 marketplace 自動更新可能會間歇性失敗。864* 可以在不提示的情況下提供儲存認證的助手會驗證檢查。Git Credential Manager、macOS Keychain 助手和 `git-credential-store` 在持有主機的認證後以這種方式運作。
865* 需要提示您的助手無法在背景中回答。更新會無聲地失敗，現有簽出會保留在原位，因此您的 plugin 會從最後同步的狀態繼續運作。執行 `/plugin marketplace update <name>` 以使用您的認證重新整理 marketplace。
866
867當檢查發現簽出是最新的時，Claude Code 會保持原樣。當檢查發現新提交，或因為無法到達或驗證遠端而失敗時，Claude Code 會重新複製 marketplace 並交換新複製。如果該複製失敗，現有簽出會保留在原位。重新複製可能會在大型儲存庫上[逾時](#git-operations-time-out)。
865 868
866兩個設定使私人 marketplace 的行為可預測：869兩個設定使私人 marketplace 的行為可預測：
867 870
868* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景檢查無法到達或驗證遠端時保留現有簽出，而不嘗試重新複製。您的 plugin 會從最後同步的狀態繼續運作，使用 `/plugin marketplace update` 的手動更新仍會使用您的認證進行驗證。871* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景檢查無法到達或驗證遠端時保留現有簽出，而不嘗試重新複製。您的 plugin 會從最後同步的狀態繼續運作，使用 `/plugin marketplace update` 的手動更新仍會使用您的認證進行驗證。
869* 配置 git 認證助手，例如使用 `gh auth setup-git` 針對 GitHub，以便重新複製可以在不提示的情況下進行驗證。872* 配置 git 認證助手，例如使用 `gh auth setup-git` 針對 GitHub，以便背景檢查和重新複製可以在不提示的情況下進行驗證。
870 873
871在您的環境中設定提供者令牌（例如 `GITHUB_TOKEN`）本身不會啟用背景驗證。令牌只有透過已配置的認證助手（例如 `gh` CLI 的助手，它讀取 `GH_TOKEN` 和 `GITHUB_TOKEN`）才會生效。874在您的環境中設定提供者令牌（例如 `GITHUB_TOKEN`）本身不會啟用背景驗證。令牌只有透過已配置的認證助手（例如 `gh` CLI 的助手，它讀取 `GH_TOKEN` 和 `GITHUB_TOKEN`）才會生效。
872 875
873若要使背景檢查本身透過 HTTPS 進行驗證，請配置全域 git URL 重寫。重寫會在遠端 URL 中嵌入令牌，因此即使背景檢查停用認證助手，它也會生效。當檢查發現簽出是最新的時，Claude Code 會跳過重新複製。以下範例會重寫 marketplace 儲存庫的 URL 以包含存取令牌：
874
875```bash theme={null}
876git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"
877```
878
879將重寫範圍限制在 marketplace 儲存庫或組織路徑。其基礎僅為主機的重寫適用於該機器上對該主機的每次 fetch 和 push，並覆蓋您的正常認證，包括推送到您自己的儲存庫。
880
881每個提供者在重寫的 URL 中預期不同的使用者名稱，相同的路徑範圍適用於每個提供者。對於自託管伺服器，請將主機名稱替換為您的伺服器主機名稱：
882
883| 提供者 | 重寫的 URL 形式 |
884| :-------- | :---------------------------------------------------------------- |
885| GitHub | `https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins` |
886| GitLab | `https://oauth2:YOUR_TOKEN@gitlab.com/acme-corp/plugins` |
887| Bitbucket | `https://x-token-auth:YOUR_TOKEN@bitbucket.org/acme-corp/plugins` |
888
889重寫會以純文字形式將令牌儲存在您的 gitconfig 中，因此請使用具有對 marketplace 儲存庫的唯讀存取權的令牌。
890
891<Note>876<Note>
892 在 CI/CD 環境中，在從私人儲存庫安裝 plugin 之前配置 git 認證助手。在 GitHub Actions 上，匯出具有對 marketplace 儲存庫的讀取存取權的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人 marketplace 需要個人存取令牌或應用程式令牌。877 在 CI/CD 環境中，在從私人儲存庫安裝 plugin 之前配置 git 認證助手。在 GitHub Actions 上，匯出具有對 marketplace 儲存庫的讀取存取權的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人 marketplace 需要個人存取令牌或應用程式令牌。
893
894 如果您在管道中配置全域 URL 重寫，重寫也會直接驗證背景檢查。
895</Note>878</Note>
896 879
897<h3 id="distribute-through-organization-settings">880<h3 id="distribute-through-organization-settings">
1620 1603
1621對於背景自動更新：1604對於背景自動更新：
1622 1605
1623* 根據預設，背景重新整理會停用 git 認證助手以進行拉取，因此拉取無法透過 HTTPS 進行驗證。具有在 `ssh-agent` 中載入的金鑰的 SSH 遠端仍會進行驗證1606* 背景檢查使用您配置的 git 認證助手，但永遠不會提示，因此您的助手必須能夠使用儲存的認證回答。具有在 `ssh-agent` 中載入的金鑰的 SSH 遠端也會進行驗證
1624* 當拉取無法驗證時，Claude Code 會使用您儲存的認證重新複製 marketplace，但重新複製可能在大型儲存庫上逾時1607* 如果您的助手需要提示您，背景更新會以無聲方式失敗，現有複製保持原位。先登入您的助手，以便它為主機保存認證。對於 GitHub，執行 `gh auth login`，然後執行 `gh auth setup-git`
1625* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景拉取無法到達或驗證遠端時保留現有複製而不嘗試重新複製1608* 當檢查找到新提交，或無法到達或驗證遠端時，Claude Code 使用相同的認證重新複製 marketplace。重新複製可能在大型儲存庫上逾時
1626* 配置 git 認證助手（例如 `gh auth setup-git`），以便重新複製可以驗證1609* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景檢查無法到達或驗證遠端時保留現有複製而不嘗試重新複製
1627* 如果重新複製在大型儲存庫上逾時，請使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制1610* 如果重新複製在大型儲存庫上逾時，請使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制
1628* 配置範圍限定於 marketplace 儲存庫的 [git URL 重寫](#private-repositories)，以便背景拉取直接驗證
1629* 或使用 `/plugin marketplace update <name>` 手動更新私人 marketplace，這會使用您的認證1611* 或使用 `/plugin marketplace update <name>` 手動更新私人 marketplace，這會使用您的認證
1630 1612
1613在 v2.1.280 之前，背景檢查執行時沒有您的認證助手，無法驗證透過 HTTPS 的私人儲存庫。
1614
1631<h3 id="marketplace-updates-fail-in-offline-environments">1615<h3 id="marketplace-updates-fail-in-offline-environments">
1632 Marketplace 更新在離線環境中失敗1616 Marketplace 更新在離線環境中失敗
1633</h3>1617</h3>
1634 1618
1635**症狀**：在離線或隔離環境中，背景 marketplace 重新整理無法到達遠端，Claude Code 重複嘗試無法成功的重新複製。1619**症狀**：在離線或隔離環境中，背景 marketplace 重新整理無法到達遠端，Claude Code 重複嘗試無法成功的重新複製。
1636 1620
1637**原因**：背景重新整理檢查 marketplace 的遠端以尋找新提交，當拉取無法到達遠端時，Claude Code 嘗試再次複製 marketplace。離線時，複製以相同方式失敗，現有複製保持原位。在 v2.1.274 之前，重新整理在現有複製中執行 `git pull`，當拉取失敗時將複製移到一邊以重新複製，並在之後以盡力而為的基礎上還原它。1621**原因**：背景重新整理檢查 marketplace 的遠端以尋找新提交，當檢查無法到達遠端時，Claude Code 嘗試再次複製 marketplace。離線時，複製以相同方式失敗，現有複製保持原位。在 v2.1.274 之前，重新整理在現有複製中執行 `git pull`，當拉取失敗時將複製移到一邊以重新複製，並在之後以盡力而為的基礎上還原它。
1638 1622
1639重新整理在啟動後在背景中執行，因此不會延遲啟動。每個工作階段仍會重複失敗的嘗試，每個 git 操作都可以等待 [120 秒逾時](#git-operations-time-out)。1623重新整理在啟動後在背景中執行，因此不會延遲啟動。每個工作階段仍會重複失敗的嘗試，每個 git 操作都可以等待 [120 秒逾時](#git-operations-time-out)。
1640 1624
1641**解決方案**：設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在拉取無法到達遠端時跳過重新複製嘗試並繼續使用現有複製：1625**解決方案**：設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在檢查無法到達遠端時跳過重新複製嘗試並繼續使用現有複製：
1642 1626
1643```bash theme={null}1627```bash theme={null}
1644export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11628export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
