grafana-plugin-scaffolding

Grafana 插件脚手架技能

使用官方 @grafana/create-plugin 脚手架自动创建 Grafana 插件项目。此技能适用于所有插件类型，可处理项目脚手架搭建、开发环境设置和初始配置。

**支持的 Grafana 版本：**仅 v12.x+

说明

第 1 步：验证前置条件

开始搭建脚手架前，请确认已安装以下工具：

# Check Node.js (v18+ required)
node --version

# Check npm
npm --version

# Check Docker (optional, for local development)
docker --version

如果缺少前置条件，请引导用户安装：

• Node.js：https://nodejs.org/
• Docker Desktop：https://www.docker.com/products/docker-desktop/

第 2 步：搭建插件脚手架

使用官方 @grafana/create-plugin 工具：

# Interactive scaffolding (recommended)
npx @grafana/create-plugin@latest

# The tool will prompt for:
# - Plugin type (panel, datasource, app, scenesapp)
# - Organization name (e.g., "myorg")
# - Plugin name (e.g., "my-panel")
# - Include backend? (y/n)

第 3 步：进入目录并安装依赖

# Navigate to the new plugin directory
cd <orgName>-<pluginName>-<pluginType>

# Install frontend dependencies
npm install

# Install backend dependencies (if backend plugin)
go mod tidy

第 4 步：启动开发环境

选项 A：使用 Docker 热重载（推荐）

脚手架会生成 docker-compose.yaml。如需通过文件监听增强开发体验，请使用 templates/docker-compose.yaml 中的模板，该模板包含 Docker Compose develop 功能。

# Start Grafana with file watching (Docker Compose v2.22.0+)
docker compose watch

# Or standard start without watching
docker compose up -d

# Access Grafana at http://localhost:3000
# Login: admin / admin

使用 docker compose watch 时：

• dist/ 中的前端更改会自动同步（无需重启）
• 后端二进制文件更改（gpx_*）会触发容器重启
• 无需手动执行构建和重启流程

选项 B：手动操作

# Build and watch frontend
npm run dev

# Build backend (if applicable)
mage -v

# Configure Grafana to load unsigned plugins
# Add to grafana.ini: plugins.allow_loading_unsigned_plugins = <plugin-id>

第 5 步：验证插件安装

1. 打开 http://localhost:3000
2. 前往 Administration > Plugins
3. 搜索插件名称
4. 确认插件已显示且可以添加到仪表板

插件类型工作流

面板插件

npx @grafana/create-plugin@latest
# Select: panel
# Enter: organization name
# Enter: plugin name
# Backend: No (panels don't need backend)

搭建脚手架后：

1. 编辑 src/components/SimplePanel.tsx，实现可视化逻辑
2. 编辑 src/types.ts，设置面板选项接口
3. 编辑 src/module.ts，配置选项

数据源插件（仅前端）

npx @grafana/create-plugin@latest
# Select: datasource
# Enter: organization name
# Enter: plugin name
# Backend: No

搭建脚手架后：

1. 编辑 src/datasource.ts，实现查询逻辑
2. 编辑 src/ConfigEditor.tsx，设置连接参数
3. 编辑 src/QueryEditor.tsx，设置查询构建器 UI

数据源插件（含后端）

npx @grafana/create-plugin@latest
# Select: datasource
# Enter: organization name
# Enter: plugin name
# Backend: Yes

搭建脚手架后：

1. 编辑 pkg/plugin/datasource.go，实现 Go 查询逻辑
2. 实现 QueryData 和 CheckHealth 方法
3. 构建后端：mage -v

应用插件

npx @grafana/create-plugin@latest
# Select: app
# Enter: organization name
# Enter: plugin name
# Backend: Optional

搭建脚手架后：

1. 编辑 src/pages/，设置应用页面
2. 更新 plugin.json 中的 includes，以配置导航
3. 将新页面添加为 React 组件

开发命令

# Frontend development (watch mode)
npm run dev

# Frontend production build
npm run build

# Backend build (Go plugins)
mage -v

# Run unit tests
npm test

# Run E2E tests (requires Grafana running)
npx playwright test

# Lint code
npm run lint

# Type check
npm run typecheck

E2E 测试

@grafana/create-plugin 脚手架包含基于 @grafana/plugin-e2e 和 Playwright 的 E2E 测试配置。

# Install Playwright browsers
npx playwright install --with-deps chromium

# Start Grafana
docker compose up -d

# Run E2E tests
npx playwright test

# Run with UI mode (debugging)
npx playwright test --ui

全面的测试模式、fixture 和 CI/CD 配置请参阅 references/e2e-testing.md。

最佳实践

1. 从简单开始：先实现最基本的功能，再逐步迭代
2. 使用 Docker：确保团队成员使用一致的环境
3. 尽早测试：开发过程中频繁运行测试
4. 类型安全：所有前端代码都应利用 TypeScript
5. SDK 更新：保持 @grafana/data、@grafana/ui 和 @grafana/runtime 版本一致

常见问题

插件未显示

• 检查 plugin.json 中的 id 字段是否正确
• 确认 Docker 卷挂载正确
• 确保 npm run dev 已完成且未报错

后端插件错误

• 运行 mage -v 重新构建 Go 代码
• 检查 dist/ 中是否存在 plugin_start_linux_* 或 gpx_* 二进制文件
• 确认 plugin.json 中包含 "backend": true

开发服务器问题

• 清除浏览器缓存
• 重启 Docker：docker compose down && docker compose up -d
• 查看 Grafana 日志：docker compose logs grafana

委派

对于复杂的架构决策、插件设计模式或故障排查，请委派给 grafana-plugin-expert Agent；该 Agent 可通过 Context7 访问当前 SDK 文档。