# 發佈套件 — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

將套件發佈到 AI Game Dev 社群登錄庫：認領發佈者、上傳、發行說明、beta 通道、棄用、撤回，以及其他來源。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/app/publishing-packages)。

社群登錄庫是使用者依 id 尋找與安裝套件的地方：`gamedev pkg add acme.level-tools`，或在 Packages 視窗中按 **Browse**，並具備自動更新與 1 到 5 星評分。任何註冊的 ai-game.dev 帳號都能發佈，套件免費，而且每個版本都會通過自動檢查，不需人工審核。本頁涵蓋完整流程：你的發佈者、首次上傳、發行說明、預先發行通道、棄用、撤回，以及其他分享套件的方式。

![ai-game.dev 上的套件目錄：一個精選引擎套件、分類篩選，以及一排排官方與社群套件](https://ai-game.dev/images/wiki/app/catalog-packages.webp)

套件目錄：官方套件與社群套件，各自附有安裝指令。

## 認領發佈者

你的發佈者 id 是你所發佈的每個套件 id 的前半段（`acme.level-tools` 中的 `acme`）。只需認領一次；先搶先贏：

```bash
gamedev login
gamedev pkg publisher claim acme --name "Acme Tools"
```

發佈者 id 為 2 到 40 個小寫字母、數字與單一連字號。AI Game Dev 自家的 id（`aigd`）、引擎名稱（`unity`、`godot`、`unreal`、`brutal`、`bevy`、`threejs`）、商標，以及 `un1ty` 或 `unity-tools` 這類相似名稱皆為保留。帳號需要已驗證的電子郵件，且最多可持有 3 個發佈者。

認領發佈者的帳號就是它的 **owner**。擁有者可依電子郵件新增 **maintainers**；維護者可以上傳、撤回、棄用、編輯發行說明、移動通道以及簽發權杖。只有擁有者能管理成員與[信任的發佈者](https://ai-game.dev/zh-hant/docs/wiki/app/trusted-publishing)。

## 發佈版本

在 `aigd-package.json` 中放入 `"publisher": "acme"`，調高 `version`，建置，然後：

```bash
gamedev pkg publish level-tools
```

CLI 會打包資料夾（與 `gamedev pkg pack` 相同的檢查與位元組）、上傳，並等待檢查結果。版本會經歷這些狀態：

| 狀態 | 說明 |
| --- | --- |
| `uploaded`、`checking` | 等待中或正在執行自動檢查 |
| `published` | 通過所有檢查；約一分鐘內進入簽署索引 |
| `rejected` | 某項檢查失敗；報告會列出每一項失敗。修正後重新上傳同一版本 |
| `yanked` | 由發佈者撤回：版本範圍會略過它，已安裝的則保留 |
| `revoked` | 由 AI Game Dev 移除（惡意軟體、帳號遭盜用）：所有應用程式都會將它停用 |

**版本不可變。** 已發佈、已撤回或已撤銷的版本號永遠無法再次上傳；只有被拒絕的可以。修正請以新版本發佈。

![目錄中某個套件的頁面：名稱、發佈者、版本、安裝按鈕與指令、入門範例預覽、About 面板以及最新版本](https://ai-game.dev/images/wiki/app/catalog-package-page.webp)

目錄中某個社群套件的頁面。使用者只要一鍵或一行指令就能安裝。

## 發行說明

每個版本都可以附上 Markdown 格式的發行說明。使用者會在 Packages 視窗（**Versions**）以及發佈者面板中依版本看到。上傳時一併提供：

```bash
gamedev pkg publish level-tools --notes RELEASE_NOTES.md
```

若沒有 `--notes`，登錄庫會從你的 `CHANGELOG.md`（位於套件資料夾中，並隨封存檔一起送出）擷取該版本標題（`## 1.2.0`、`## [1.2.0]` 或 `## v1.2.0`）到下一個同級或更高級標題之間的段落，上限 20 KB：

```text
# Changelog

## [1.2.0]

- Export levels as glTF.
- Fix the collectible count in nested scenes.
```

發行說明最多為 20 KB 的 Markdown，會像 README 一樣經過清理，並與套件中其他文字一樣接受提示注入檢查。成員之後可在發佈者面板中編輯。簽署索引會攜帶前 4 KB，並附上其餘內容的連結。

## 通道：latest、beta 與其他

通道（dist-tag）指定使用者依名稱索取時取得的版本：

```bash
gamedev pkg add acme.level-tools          # the latest channel
gamedev pkg add acme.level-tools@beta     # whatever beta points to
```

- 預先發行版本（`1.3.0-beta.1`）預設永遠不會被安裝：`latest` 是你未設定時最高的已發佈穩定版本，且永遠不能指向預先發行版本。
- 其他通道由你命名（`beta`、`next`、`nightly`）：小寫、以字母開頭、最多 16 個字元。一個套件最多 5 個通道，包含 `latest`。
- 已撤回或已撤銷的版本無法標記；指向被撤回版本的通道會被移除。
- 以 semver 預先發行版本的形式發佈預先發行版本（`1.3.0-beta.2`）。若預先發行版本命名為 `alpha`、`beta`、`rc`、`next`、`preview`、`canary`、`nightly`、`dev` 或 `experimental`，會自動將該通道移到它身上，除非成員手動設定過該通道；任何通道也可在發佈者面板（**Channels**）中移動。
- `gamedev pkg add acme.level-tools@beta` 會把該通道寫進 `packages.json`，內容為 `{ "source": "^1.3.0-beta.1", "channel": "beta" }`。只要通道版本比最新的穩定版還新，測試者就會取得該通道版本；等穩定版推出後，他們下一次更新就會轉移到穩定版。

## 棄用套件或版本

棄用會在不得破壞任何已安裝內容的前提下，提示使用者改用其他版本：

- **套件：** 一則訊息（最多 300 個字元），以及可選的替代套件 id。應用程式與 CLI 會顯示該訊息與替代套件；已安裝的副本仍可繼續運作，該套件也仍然可以加入。
- **版本：** 一則訊息，例如「匯出巢狀場景時會遺失資料，請更新至 1.2.1」。

選擇版本時，應用程式會偏好未被棄用的版本。兩種棄用都可復原，並會記錄在 registry 的稽核記錄中。請在發佈者面板中設定。

## 撤回與撤銷

撤回你不小心發佈的版本：此後版本範圍會略過它，但已經安裝它的使用者仍會保留。撤回是可復原的，發佈者權杖也可以執行撤回。撤銷則是 AI Game Dev 針對惡意或被竊取版本的緊急關閉機制：它會從索引中移除，而每個已安裝該版本的應用程式會在下一次讀取索引時將它關閉。

## 從 CI 發佈

有兩種方式，皆說明於[受信任發佈](https://ai-game.dev/zh-hant/docs/wiki/app/trusted-publishing)：

- **受信任發佈（建議）：** 由 GitHub Actions 或 GitLab CI 證明是哪個儲存庫與工作流程在發佈；不需要在任何地方儲存密鑰，且每個版本都會記錄其來源。該頁也說明了可直接使用的 GitHub Action 與 GitLab CI 範本：[IvanMurzak/gamedev-publish-action](https://github.com/IvanMurzak/gamedev-publish-action)。
- **發佈者權杖：** `gamedev pkg publisher token create acme --label ci --days 90`，儲存為 CI 密鑰並以 `AI_GAME_DEV_PUBLISHER_TOKEN` 傳遞。

## 發佈者面板

首次上傳後，發佈者需要管理的一切都在 [ai-game.dev/publisher](https://ai-game.dev/publisher) 的發佈者面板中，供已登入的擁有者與維護者使用：你的發佈者與套件、每個版本及其狀態與檢查報告、發行說明、通道、棄用與撤回、成員與角色、發佈者權杖，以及附有可複製工作流程片段的受信任發佈者。請參閱 [Registry 規則與檢查](https://ai-game.dev/zh-hant/docs/wiki/app/package-registry#panel)。

## 其他來源：GitHub、npm 與資料夾

registry 並不是分享套件的唯一方式。這些來源在安裝時不會經過 registry 的檢查，因此請自行執行 `gamedev pkg validate`；而要分享使用 proposed API 的套件，也只能靠這些來源：

```bash
gamedev pkg add github:acme/level-tools           # the default branch: moves with each push
gamedev pkg add github:acme/level-tools@v1.2.0    # a tag: pinned, never auto-updated
gamedev pkg add npm:acme-level-tools@^1.2.0       # an npm package and range
gamedev pkg add file:../level-tools               # a folder
```

- **GitHub：** 若使用標籤，應用程式會下載名稱以 `.aigd.tgz` 結尾的 release asset（請附上 `gamedev pkg pack` 產生的檔案）；否則會取得該 commit 的儲存庫，因此 `aigd-package.json` 必須位於根目錄，且 `dist/` 必須已提交。
- **npm：** 對套件資料夾執行 `npm publish`。npm 封存檔必須包含 `aigd-package.json` 與 `dist/`；也請在 `package.json` 中加入 `"engines": { "aigd": "<range>" }`，這樣應用程式就能略過無法執行的版本，而不必先下載它們。
- **團隊：** 在 Project 層級加入套件，讓它提交到 `.ai-game-dev/packages.json`，每位隊友都會取得相同版本，並由專案的鎖定檔固定。

## 相關頁面

- [受信任發佈](https://ai-game.dev/zh-hant/docs/wiki/app/trusted-publishing)：不需儲存密鑰的 CI。
- [Registry 規則與檢查](https://ai-game.dev/zh-hant/docs/wiki/app/package-registry)：了解檢查會拒絕哪些內容。
- [套件 CLI 參考](https://ai-game.dev/zh-hant/docs/wiki/app/package-cli#publish)：了解每個 `publish` 選項。

---

Source (HTML): https://ai-game.dev/zh-hant/docs/wiki/app/publishing-packages

Machine-translated (zh-Hant) from the English page: https://ai-game.dev/docs/wiki/app/publishing-packages
