emdash-github-actions

EmDash 插件 GitHub Actions

此技能可帮助你使用 GitHub Actions 为 EmDash 插件设置全面的 CI/CD 流水线。EmDash 是基于 Astro 的全栈 TypeScript CMS，因此其插件生态完全基于 TypeScript。

此技能涵盖的内容

健康的 EmDash 插件应配置几类工作流。并非每个插件都需要全部工作流——合适的组合取决于插件的复杂程度、是否有 React 管理界面、是否有测试等。你需要判断哪些工作流适用，并进行设置。

工作流分为以下几类：

1. 类型检查 — 使用 emdash 对等依赖进行 TypeScript 严格模式检查
2. 代码质量 — 支持 TypeScript 的 ESLint
3. 测试 — Vitest 或类似的 TypeScript 原生测试运行器
4. 安全性 — 使用 npm audit 检查依赖漏洞
5. 部署 — 在标签/发布时自动发布到 npm

阅读 references/workflows.md，了解每种工作流的详细配置，包括可直接使用的 YAML 模板和配置文件。

如何处理请求

步骤 1：了解插件

编写任何工作流文件之前，先了解你正在处理的项目：

• 插件的功能是什么？ 查看 package.json 中的描述和 src/index.ts 导出内容。EmDash 插件通常会挂接 page:metadata、page:fragment、内容钩子，或提供管理界面。
• 是否有 React 管理界面？ 检查是否有 .tsx 文件或 admin.tsx。如果有，类型检查需要 @types/react 和 --jsx react-jsx。
• 是否有测试？ 检查是否有 tests/ 或 __tests__/ 目录，或 vitest.config.ts。如果有，则设置测试工作流。如果没有，可以指出添加测试会很有价值，但不要强行要求。
• 有哪些对等依赖？ 查看 package.json 中的 peerDependencies。EmDash 插件始终依赖 emdash，也可能依赖 react、astro 等。
• 是否使用其他 npm 依赖？ 检查 package.json 中是否有 dependencies。如果有，CI 需要添加 npm install 步骤。
• 是否已发布到 npm？ 检查包名是否带作用域（例如 @org/emdash-plugin-foo），以及是否有 publishConfig。如果有，则适用部署工作流。

步骤 2：推荐一组工作流

根据你的发现，推荐要设置的工作流。大多数插件适用的默认方案：

• TypeScript 类型检查（几乎总是需要——这是最有价值的检查）
• ESLint（如果插件文件不止寥寥几个）
• npm audit（安全检查成本低，几乎总是值得采用）

按需添加：

• Vitest 测试（如果存在测试）
• npm publish（如果插件已发布到 npm）

步骤 3：创建工作流文件

在 .github/workflows/ 中为每个工作流创建单独的 YAML 文件。使用多个文件而非单个大型工作流，能让 PR 中的反馈更清晰（每项检查都会单独显示），也更便于启用或禁用单项检查。

以 references/workflows.md 中的模板为起点，并根据具体插件进行调整。常见调整包括：

• 如果插件有 .tsx 文件，则添加 @types/react
• 添加提供类型的其他对等依赖
• 调整类型检查和 lint 命令的文件路径
• 配置 npm 发布作用域和访问级别

步骤 4：创建辅助配置文件

根据你设置的工作流，可能还需要：

• tsconfig.json — TypeScript 配置（如果尚不存在）
• eslint.config.js — 支持 TypeScript 的 ESLint flat config
• vitest.config.ts — Vitest 配置

第 5 步：设置密钥提醒

如果你要添加 npm 发布工作流，请提醒用户需要在 GitHub 中配置仓库密钥：

• NPM_TOKEN — 具有发布权限的 npm 访问令牌

引导他们前往：Repository Settings > Secrets and variables > Actions > New repository secret。

对于作用域包（@org/package-name），令牌必须具有组织访问权限。

命名约定

使用描述性工作流文件名，让每个文件的用途一目了然：

• ci.yml — TypeScript 类型检查（主要 CI 检查）
• lint.yml — ESLint
• test.yml — Vitest/测试运行器
• security.yml — npm audit
• publish.yml — 发布时执行 npm 发布

重要细节

Node.js 版本：默认使用 Node.js 22。EmDash 基于现代 TypeScript 和 Astro 构建，因此无需支持较旧的 Node.js 版本。使用 actions/checkout@v5 和 actions/setup-node@v5（v5 在 Node.js 24 运行器上运行，可避免 Node.js 20 弃用问题）。

安装对等依赖：EmDash 插件将 emdash 声明为对等依赖。在 CI 中进行类型检查时，必须显式安装 emdash（如果插件包含 .tsx 文件，还需安装 @types/react），因为独立插件仓库不会自动安装对等依赖。

--skipLibCheck 标志：在 CI 中运行 tsc 时使用 --skipLibCheck。EmDash 及其传递依赖可能存在与插件作者无关的内部类型问题。--skipLibCheck 会跳过对 .d.ts 文件的检查，同时仍会完整检查插件自身的源代码。

用于发现文件的 find 命令：不要在 CI 命令中使用 src/**/*.ts 这类 shell 通配符——如果某个目录深度下没有匹配文件，它们就会失败。请改用 $(find src -name '*.ts' -o -name '*.tsx')。

分支命名：大多数 EmDash 插件仓库将 main 设为默认分支。务必检查实际仓库，并在工作流触发器中使用正确的分支名称。