分發原生外掛程式

原生外掛程式透過 npm 分發，而非應用市集。沒有打包器、沒有清單檔案、也沒有安全稽核步驟 — 只是一個匯出描述符工廠和 createPlugin 的常規 npm 套件。網站營運者使用 npm install 安裝它，並在 astro.config.mjs 中註冊。

套件結構

典型的原生外掛程式套件：

@my-org/plugin-analytics/
├── src/
│   ├── index.ts          # Descriptor + createPlugin
│   ├── admin.tsx         # React admin components (optional)
│   └── astro/            # Astro components for PT block rendering (optional)
│       └── index.ts
├── dist/                 # build output
├── package.json
├── tsconfig.json
└── README.md

package.json

{
	"name": "@my-org/plugin-analytics",
	"version": "0.1.0",
	"type": "module",
	"main": "dist/index.js",
	"exports": {
		".": {
			"types": "./dist/index.d.ts",
			"import": "./dist/index.js"
		},
		"./admin": {
			"types": "./dist/admin.d.ts",
			"import": "./dist/admin.js"
		},
		"./astro": {
			"types": "./dist/astro/index.d.ts",
			"import": "./dist/astro/index.js"
		}
	},
	"files": ["dist"],
	"scripts": {
		"build": "tsdown src/index.ts src/admin.tsx --format esm --dts --clean",
		"prepublishOnly": "pnpm build"
	},
	"peerDependencies": {
		"emdash": "*",
		"react": "^18.0.0"
	}
}

如果你的外掛程式不需要 ./admin 和 ./astro 匯出，可以跳過它們。

建置組態

原生外掛程式以 ES 模組形式發布。大多數作者使用 tsdown（或 tsup）配合 TypeScript。將 react、emdash 和 @emdash-cms/admin 外部化，使它們不會被打包到輸出中：

export default {
	entry: {
		index: "src/index.ts",
		admin: "src/admin.tsx",
	},
	format: "esm",
	dts: true,
	external: ["react", "react-dom", "emdash", "@emdash-cms/admin"],
};

如果你發布用於 Portable Text 渲染的 Astro 元件，這些元件不需要打包 — Astro 直接使用 .astro 原始檔案。在 files 下列出 astro/ 目錄，以便它們被包含在 npm 壓縮包中。

版本管理

使用語意化版本。升級主版本號是向營運者發出的訊號，表示他們在升級時可能需要進行變更。definePlugin() 的形狀和外掛程式上下文 API 是穩定的，但如果你變更外掛程式的鉤子行為、能力要求或設定模式，且會影響現有安裝，那就是一個破壞性變更。

能力是外掛程式表面契約的一部分。在非主版本發布中新增能力意味著現有營運者升級時會靜默授予新能力 — 這對於沙盒外掛程式來說沒問題，因為同意對話方塊會重新提示，但原生外掛程式沒有同意流程。將能力新增視為原生外掛程式的主版本升級，或在發布說明中非常明顯地記錄它們。

README 和文件

一個好的外掛程式 README 應包含：

• 外掛程式的功能，用一句話說明。
• 如何安裝（npm install ... 以及帶有 import 的 astro.config.mjs 程式碼片段）。
• 它宣告了哪些能力以及用於什麼目的。
• 任何必需的 Astro 範本變更（例如用於 page:metadata 的 <EmDashHead />，用於 page:fragments 的 <EmDashBodyEnd />）。
• 設定及每個設定控制的內容。
• 主版本之間的遷移說明。

發布到 npm

npm version patch     # or minor/major
npm publish --access public

對於作用域套件，首次發布時需要 --access public（npm 預設將作用域套件設為私有）。

針對宿主網站的本地開發

在迭代外掛程式時，將其連結到測試網站，而不是每次變更都重新發布：

# In the plugin package
pnpm build --watch

# In the test site
pnpm add file:../plugins/my-plugin
# or with workspaces:
pnpm add @my-org/plugin-analytics --workspace

然後在測試網站的 astro.config.mjs 中註冊外掛程式並執行開發伺服器。鉤子處理程式會在 pnpm build 完成後的下一次請求時執行。

應用市集？不行。

原生外掛程式無法發布到 EmDash 應用市集。應用市集僅支援沙盒外掛程式：每個發布的外掛程式都會經過 emdash plugin bundle（驗證後端程式碼是自包含的、不匯入 Node.js 內建模組、且保持在大小限制內）、進行安全稽核，並在安裝時在沙盒執行階段中執行。

如果你想要應用市集的分發管道，但你的外掛程式目前使用僅限原生的特性，請考慮是否真的需要它們 — 許多外掛程式可以放棄 page:fragments 或從 settingsSchema 轉換為 Block Kit 設定頁面，從而變為可沙盒化。請參閱選擇外掛程式格式了解權衡。