跳到主内容

发布最佳实践

发布 Grafana 插件时，遵循最佳实践不仅能确保提交和审查过程顺利进行，还能为用户提供更高质量的体验。通过遵循既定指南，可以提高插件在 Grafana 生态系统中的性能、安全性和可发现性，确保你的插件成为 Grafana 插件的优秀典范。

在继续之前，我们假设你已经创建了你的初始插件，查阅了插件开发最佳实践指南，并熟悉了关于插件签名级别的指导。

本文档概述了在发布 Grafana 插件之前应遵循的基本最佳实践。这些建议将帮助你避免常见的陷阱，简化审查流程，并创建能够无缝集成到用户工作流中的插件，同时保持 Grafana 生态系统所期望的高标准。无论是微调插件的功能，还是准备文档，遵循这些实践都将确保你的插件从一开始就为成功做好了优化。

填写插件的元数据​

元数据在使 Grafana 插件可发现和用户友好方面起着至关重要的作用。正确组织 plugin.json 文件中的元数据不仅有助于用户在Grafana 插件目录中找到你的插件，还提供了关于插件功能和兼容性的基本详细信息。

以下是需要重点关注的关键组件的细分

插件名称

name

你的插件名称应该清晰、简洁且具有描述性。它是潜在用户的第一个接触点，因此避免使用过于通用或隐晦的名称。力求名称能够反映插件的主要功能，使其目的易于一目了然。

描述

info.description

描述字段应简洁地总结你的插件功能以及用户为什么要安装它。将描述限制在两句话内，突出核心功能和用例。精心编写的描述不仅能告知用户，还有助于在目录中获得更好的搜索结果。

关键词

info.keywords

关键词能提高你的插件在 Grafana 目录中的可搜索性。选择准确描述插件功能和支持的数据类型（例如，“JSON”、“SQL”、“可视化”）的术语。

注意

避免关键词堆砌；不相关的关键词将在审查过程中被标记，可能延迟发布。

Logo

info.logos

添加 Logo 可以改善插件在插件目录中的整体外观。提供 Logo 可以增加插件的合法性和专业性。

截图

info.screenshots

screenshots 字段应用于提供一个包含一个或多个截图图像的数组，这些图像将显示在插件目录中。这非常有助于向用户提供插件的可视化表示，并帮助他们在安装之前确定此插件是否能解决他们的问题。务必提供插件实际运行的截图，突出其亮点功能。

注意

确保你的截图分辨率和文件类型合适（例如 png、jpeg 或 gif）。

赞助链接

info.links

在插件的元数据中添加赞助链接提供了一种用户支持你的工作的方式。此链接会出现在插件详情页的“链接”部分，方便认为你的插件有价值的用户为其开发做出贡献。赞助链接支持各种资金平台，例如 GitHub Sponsors、Patreon 等。

示例

{
  info: {
    links: [
      {
        name: "sponsorship",
        url: "https://github.com/sponsors/pluginDeveloper"
      }
    ]
  }
}

Grafana 版本兼容性

dependencies.grafanaDependency

确保你的插件指定了兼容的最低 Grafana 版本。这保证了运行不同版本 Grafana 的用户知道你的插件是否适用于他们。务必运行端到端测试以确认与你支持的版本的兼容性。

创建一份全面的 README​

你的插件 README 文件既是给用户的第一印象，也是详细的使用指南。可以将其视为一个结合了店面广告和说明手册的文件——展示插件的功能、安装方法以及用户如何在他们的 Grafana 实例中充分利用它。

为了帮助开发者编写高质量的 README，我们提供了一个README 模板，它是 create-plugin 工具生成的插件结构的一部分。此模板确保你涵盖了基本组件，同时为你提供了添加更具体细节的灵活性。

除了插件的基本概述、用例和要求之外，还应该考虑包含其他元素，以帮助用户理解插件的价值和功能

  • 截图或屏幕录像：视觉辅助工具通常比纯文本更能有效传达信息。包含截图甚至视频演示可以让用户快速掌握插件的功能和设置过程，让他们有信心有效地使用它。
  • 动态徽章：徽章可以快速提供关于插件的概览信息，例如最新版本或是否通过了安全和代码检查。可以将 shields.io 等工具与 Grafana.com API 结合使用，以便在发布新版本时自动更新这些徽章，增加插件的透明度和可信度。
  • 贡献指南：维护一个插件可能要求很高，特别是对于个人开发者而言。清楚地说明用户如何提供反馈、报告错误，并将潜在的代码贡献者引导至你的 contributing.md 文件，这些都是促进社区参与、使得随着时间的推移更容易维护和改进插件的方法。

这种结构确保你的 README 既信息丰富又引人入胜，为用户提供了自信地使用和贡献你的插件所需的一切。

维护详细的变更日志​

维护良好的变更日志对于插件透明度至关重要，并有助于用户了解不同版本之间的变化。Grafana 会在插件详情页显示你的变更日志，使其成为用户评估是否更新的关键信息来源。

信息

你可以利用我们的自动化变更日志生成功能来简化变更日志的维护过程。请遵循我们的《自动生成变更日志》指南。

变更日志最佳实践​

在你的仓库根目录使用专门的 CHANGELOG.md 文件

  1. 遵循语义化版本控制（MAJOR.MINOR.PATCH），并按版本组织条目
  2. 注明每个发布日期，以提供时间顺序上下文
  3. 按类型分组变更，例如“新功能”、“错误修复”、“重大变更”等。
  4. 引用带有链接的拉取请求，以提供额外的上下文
  5. 显著突出重大变更，以提醒用户需要执行的操作

变更日志示例：​

### [1.10.0](https://github.com/user/plugin-name/tree/1.10.0) (2025-04-05)

**Implemented enhancements:**

- Add support for dark theme [\#138](https://github.com/user/plugin-name/pull/138) ([username](https://github.com/username))
- Add ability to customize tooltip formats [\#135](https://github.com/user/plugin-name/pull/135) ([username](https://github.com/username))
- Support for PostgreSQL data source [\#129](https://github.com/user/plugin-name/pull/129) ([username](https://github.com/username))

**Fixed bugs:**

- Fix panel crash when switching dashboards [\#139](https://github.com/user/plugin-name/pull/139) ([username](https://github.com/username))
- Fix inconsistent time zone handling [\#134](https://github.com/user/plugin-name/pull/134) ([username](https://github.com/username))

**Closed issues:**

- Documentation needs examples for PostgreSQL queries [\#130](https://github.com/user/plugin-name/issues/130)

**Merged pull requests:**

- Update dependencies to address security vulnerabilities [\#140](https://github.com/user/plugin-name/pull/140) ([username](https://github.com/username))

**Breaking changes:**

- Migrate configuration storage format [\#115](https://github.com/user/plugin-name/pull/115) ([username](https://github.com/username))

通过遵循这种格式，你的变更日志将成为一个有价值的资源，清晰地传达变更、感谢贡献，并提供指向更详细信息的链接。这种透明度有助于用户对更新你的插件做出明智的决定，并展示你维护高质量 Grafana 插件的承诺。

端到端测试​

端到端 (E2E) 测试确保你的 Grafana 插件在各种环境和支持的 Grafana 版本中都能正常工作。它通过在类似于最终用户设置的环境中测试插件来模拟实际使用情况。实施 E2E 测试有助于在提交前发现问题，节省审查过程中的时间，并确保更流畅的用户体验。

关键点

  • 跨版本兼容性测试：通过设置针对多个版本的 E2E 测试，确保你的插件与不同版本的 Grafana 无缝协作。
  • 自动化测试：将 E2E 测试集成到你的持续集成 (CI) 流水线中，以便尽早且频繁地发现问题，减少审查期间的潜在问题。

有关设置 E2E 测试的完整指南，请参阅我们的《对插件进行端到端测试》文档。

验证你的插件​

在提交插件进行审查之前，请验证你的插件，以确保它符合 Grafana 关于功能、安全性和结构的各项标准。最简单的方法是使用插件验证器 (Plugin Validator)。此工具会检查可能导致你的插件无法被接受的潜在问题，例如安全漏洞或结构问题。

关键点

  • 本地运行或在 CI 中运行：你可以在本地运行验证器，或将其集成到你的 CI 工作流中以自动化验证过程。请注意，验证器会在默认的发布工作流中自动运行。
  • 验证报告：该工具会生成一份报告，突出显示在提交前需要解决的任何错误或警告。

有关使用验证器的更多信息，请参阅《插件验证器》文档。

提供预置测试环境​

为你的插件预置测试环境可以显著缩短审查时间，并使他人更容易测试和贡献你的插件。预置环境包括一个预配置的 Grafana 实例，带有示例仪表板和数据源，用于展示插件的功能。

关键点

  • 为何预置很重要：它确保审查者和贡献者无需手动设置即可快速验证插件的行为，从而加快审查和协作过程。
  • 自动化设置：你可以使用 Docker 来预置测试环境，从而创建一个即开即用的体验，模拟典型的 Grafana 设置。

要了解有关设置预置环境的更多信息，请查阅我们的预置指南。

使用 GitHub Actions 自动化发布​

为了简化插件开发工作流，最佳实践是使用 GitHub Actions 自动化发布。自动化此过程有助于确保你的插件在每次发布时都能正确构建、签名和打包，减少人为错误，加快发布过程。

关键点

  • 持续集成 (CI)：使用 GitHub Actions 在每次提交或拉取请求时自动构建和测试你的插件，尽早发现问题。
  • 发布工作流：准备发布时，自动化插件的签名和打包过程，确保它符合提交到 Grafana 插件目录所需的标准。

有关详细的设置说明，请参阅我们的《使用 GitHub 自动化打包和签名》指南。

下一步​

通过遵循这些最佳实践——例如仔细填写元数据、创建全面的 README、验证插件、预置测试环境和自动化发布——你将显著增加成功提交插件的机会。

这些最佳实践旨在确保你的插件不仅通过我们的审查过程，还能为用户提供卓越的体验。采用这些实践将简化你的工作流，并帮助创建在 Grafana 生态系统中脱颖而出的插件。

一旦你的插件准备好发布，请遵循我们的《提交插件进行审查》指南。我们期待看到你的作品！