官方模板、工程结构与 GitHub Actions¶

JetBrains 官方维护了 IntelliJ Platform Plugin Template。它不是 SDK 文档的一页，而是把官方推荐的 Gradle、源码目录、测试、运行配置、Dependabot、Changelog、签名和发布工作流落成一个可复制仓库。本章把模板中的工程实践整理成可复用清单。

模板包含什么¶

官方模板的目标是缩短插件项目启动阶段，并预配置 CI 和常见开发设施。典型结构：

.
├── .github/                 GitHub Actions、Dependabot 等
├── .run/                    IDE Run/Debug 配置
├── gradle/wrapper/          Gradle Wrapper
├── src/
│   ├── main/
│   │   ├── kotlin/          生产代码
│   │   └── resources/       plugin.xml、icons、messages
│   └── test/
│       ├── kotlin/          测试代码
│       └── testData/        测试数据
├── build.gradle.kts
├── gradle.properties
├── settings.gradle.kts
├── CHANGELOG.md
├── README.md
└── LICENSE

模板还会提供少量示例代码，例如 project startup activity、project service、tool window factory 和 resource bundle。正式插件应删除不需要的示例代码和 plugin.xml 注册项。

模板初始化检查¶

从模板创建仓库后：

启用 GitHub Actions 创建和批准 PR 的权限。
使用 Java 21 SDK 打开项目。
检查 gradle.properties 中的 group、version、pluginRepositoryUrl。
检查 plugin.xml 中的 plugin id、name、vendor、description。
移动或重命名默认 package。
删除不需要的示例 Tool Window、Service、Startup Activity。
添加真实 Plugin Logo。
添加目标 IDE、插件依赖和测试框架。

GitHub Actions：PR 构建¶

最小 PR 工作流：

name: Build

on:
  pull_request:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - uses: gradle/actions/setup-gradle@v4
      - run: ./gradlew test buildPlugin verifyPlugin

如果插件支持多产品或多 IDE 版本，把 verifier 单独放到矩阵任务，避免 PR 反馈太慢。

GitHub Actions：发布¶

发布工作流建议只在 tag 或 GitHub Release 上触发：

name: Release

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - uses: gradle/actions/setup-gradle@v4
      - run: ./gradlew signPlugin publishPlugin
        env:
          CERTIFICATE_CHAIN: ${{ secrets.CERTIFICATE_CHAIN }}
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
          PRIVATE_KEY_PASSWORD: ${{ secrets.PRIVATE_KEY_PASSWORD }}
          PUBLISH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}

建议发布前先在 beta/eap channel 验证，稳定后再发默认渠道。

Changelog 和版本¶

模板集成 Gradle Changelog Plugin，用 CHANGELOG.md 生成发布说明并 patch 到插件元数据中。维护规则：

每个版本有独立条目。
PR 合并前更新 unreleased section。
发布时版本号、changelog、tag 一致。
Marketplace 不接受同版本重复上传。

版本号建议遵循 SemVer 或与产品年度版本一致。付费插件还要考虑 release-version 和 release-date，见付费插件与许可。

Dependabot¶

模板包含 Dependabot 配置，用于更新：

GitHub Actions。
Gradle dependencies。
Gradle Wrapper。

对插件项目，依赖更新不能只看能否编译。每次升级 IntelliJ Platform、Kotlin、Gradle Plugin 后都应运行测试和 Plugin Verifier。

本仓库的文档 CI¶

本中文文档仓库不是插件源码仓库，但也应有 CI 验证 MkDocs 构建。本项目添加的工作流只做：

pip install -r requirements.txt
mkdocs build --strict --site-dir site

这样后续新增章节时，导航错误、断链和 MkDocs 配置问题会在 PR 阶段暴露。