设置开发环境

本指南将引导您设置 Grafana 插件开发的开发环境。包括

• 使用 Docker 运行已安装插件的开发版 Grafana 服务器
• 设置 GitHub 工作流程以自动化开发和发布过程
• 扩展 ESLint、Prettier、Jest、TypeScript 和 Webpack 的配置

Docker 开发环境

create-plugin 工具 包含一个以 Docker 为特色的开发环境。它允许您启动一个 Grafana 应用程序实例，插件开发者可以针对该实例进行编码。

信息

在开发期间无需对插件签名。使用 @grafana/create-plugin 构建的 Docker 开发环境将在没有签名的情况下加载插件。这是因为它默认配置为在开发模式下运行。

为何使用 Docker 环境

我们选择使用 Docker，因为它简化了创建、部署和运行应用程序的过程。它允许您为插件创建一致且隔离的环境。这使得管理依赖项变得容易，并确保插件在不同机器上以相同方式运行。

使用 create-plugin 工具，Docker 容器配置了必要的变量，以便轻松访问 Grafana 并在无需签名的情况下加载插件。插件工具还添加了实时重载功能，允许您在更改前端代码时触发浏览器刷新，更改后端代码将使插件二进制文件自动重载。

Docker 环境还允许您将调试器附加到插件后端代码，从而使开发过程更加轻松。

Docker 入门

要启动您的插件开发项目，请按列出的顺序运行以下命令

1. npm install: 安装前端依赖项。
2. npm run dev: 构建并监听插件前端代码。
3. mage -v build:linux: 构建插件后端代码。每次编辑后端文件时都要重新运行此命令。
4. npm run server: 启动运行在 https://:3000 上的 Grafana 开发服务器。

配置 Grafana 版本

要在不同版本的 Grafana 上测试插件，请设置一个环境变量。使用 GRAFANA_VERSION 设置 Grafana 版本

npm

GRAFANA_VERSION=10.0.0 npm run server

Yarn

GRAFANA_VERSION=10.0.0 yarn server

pnpm

GRAFANA_VERSION=10.0.0 pnpm run server

配置 Grafana 镜像

插件工具中的默认 Docker 镜像为 grafana-enterprise。如果您想覆盖此镜像，请通过更改 grafana_image 构建参数来修改 docker-compose.yaml，如下所示

docker-compose.yaml

version: '3.7'

services:
  grafana:
    extends:
      file: .config/docker-compose-base.yaml
      service: grafana
    build:
      args:
        grafana_version: ${GRAFANA_VERSION:-9.1.2}
        grafana_image: ${GRAFANA_IMAGE:-grafana}

此示例将环境变量 GRAFANA_IMAGE 赋给构建参数 grafana_image，默认值为 grafana。这使您可以在运行 docker compose 命令时设置值。

调试后端插件

如果您正在开发带有后端部分的插件，请运行 npm run server 并带上 DEVELOPMENT=true。docker compose 文件暴露了用于调试的端口 2345，该端口来自将在 docker 环境内运行的无头 delve 实例。您可以将调试客户端附加到此端口以调试后端代码。例如，在 VSCode 中，您可以添加如下 launch.json 配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to plugin backend in docker",
      "type": "go",
      "request": "attach",
      "mode": "remote",
      "port": 2345,
      "host": "127.0.0.1",
      "showLog": true,
      "trace": "log",
      "logOutput": "rpc",
      "substitutePath": [
        {
          "from": "${workspaceFolder}",
          "to": "/root/<your-plugin-id>"
        }
      ]
    }
  ]
}

设置 GitHub 工作流程

自动化您的开发过程，以最大程度地减少错误并使其更快、更具成本效益。create-plugin 工具可帮助您配置 GitHub Actions 工作流程，从而自动化您的开发过程。

CI 工作流程

CI (ci.yml) 工作流程旨在对前端和后端进行 lint、类型检查和构建。它还在每次您向存储库推送更改时用于对插件运行测试。create-plugin 工具有助于在开发过程早期捕获任何问题，以免它们变成更大的问题。有关作为 CI 工作流程一部分的端到端测试的更多信息，请参阅我们的文档。

发布工作流程

要了解如何自动化发布过程并设置发布工作流程，请参阅我们的文档 使用 GitHub CI 自动化打包和签名。

警告

此工作流程需要 Grafana Cloud API 密钥。在开始之前，请按照生成访问策略令牌的说明进行操作。

在 GitHub 中将您的访问策略令牌存储为仓库密钥

1. 访问仓库设置

• 转到您的 GitHub 仓库。
• 导航到“Settings”选项卡。

2. 在左侧边栏中，单击 Secrets and Variables -> Actions
3. 单击“New repository secret”按钮。
4. 添加密钥信息

• 输入密钥名称 - GRAFANA_ACCESS_POLICY_TOKEN。
• 将访问策略令牌的值粘贴到“Secret”字段中。

5. 单击“Add secret”按钮保存密钥。

密钥存储后，您可以在 GitHub Actions 工作流程中访问它

release.yml

name: Release

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: grafana/plugin-actions/build-plugin@main
        with:
          grafana_token: ${{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }}

在此示例中，使用 secrets.GRAFANA_ACCESS_POLICY_TOKEN 变量在 GitHub Actions 工作流程中安全地访问存储的令牌。请务必根据您的特定需求以及您正在使用的语言/环境调整工作流程。

触发工作流程

要触发发布工作流程，请为要发布的插件版本推送 Git 标签

git tag v1.0.0
git push origin v1.0.0

兼容性检查工作流程

兼容性检查 (is-compatible.yml) 工作流程旨在在您每次向存储库推送更改时检查插件的 Grafana API 兼容性。这有助于在发生潜在的前端运行时问题之前捕获它们。

工作流程包含以下步骤

1. 在您的插件中查找 @grafana npm 包。
2. 提取指定版本的导出类型。
3. 比较该版本与最新版本之间的差异。
4. 在您的插件中查找这些已更改 API 的用法。
5. 报告任何潜在的不兼容性。

创建插件更新工作流程

创建插件更新 (cp-update.yml) 工作流程旨在自动化插件开发环境和依赖项的更新。它会定期检查 npm 注册表中列出的最新版本 create-plugin，并将其与您的插件使用的版本进行比较。如果有新版本可用，工作流程将运行 create-plugin update 命令，更新前端依赖项锁定文件，然后创建一个包含更改的 PR 供审查。

此工作流程需要对您的插件仓库具有内容和拉取请求的写入权限，才能推送更改并打开 PR。请从以下两个选项中选择

使用默认访问令牌

要使用此选项，您必须在仓库设置中允许github actions 创建和批准拉取请求，并在工作流程中使用 permissions 属性提升默认访问令牌的权限，如下所示

name: Create Plugin Update

on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 1 * *' # run once a month on the 1st day

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: grafana/plugin-actions/create-plugin-update@main

使用个人访问令牌

要使用此选项，您必须创建一个具有访问插件仓库权限以及读取和写入 contents 和 pull requests 权限的 Github 细粒度个人访问令牌。创建后，将令牌添加到插件仓库的 action secrets 中，然后将其传递给 action，如下所示

name: Create Plugin Update

on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 1 * *' # run once a month on the 1st day

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: grafana/plugin-actions/create-plugin-update@main
        with:
          token: ${{ secrets.GH_PAT_TOKEN }}

打包统计工作流程

打包统计 (bundle-stats.yml) 工作流程旨在帮助开发者关注其插件前端资源的大小。PR 中的更改会触发此工作流程，它将比较两个 webpack 统计文件；一个来自默认分支，另一个来自 PR。然后计算这些资源大小之间的差异，并向 PR 发布格式化的评论，概述任何大小差异。

bundle-stats.yml

name: Bundle Stats

on:
  workflow_dispatch:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write
  actions: read

jobs:
  compare:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - uses: grafana/plugin-actions/bundle-size@main

故障排除

找不到主要统计 Artifact

如果您在打包大小工作流程运行时看到此警告，这意味着工作流程未能找到包含 main 分支统计文件的 github artifact。该文件可以通过将 PR 合并到 main、向 main 推送提交或使用 workflow_dispatch 手动运行工作流程来生成。

扩展配置

.config/ 目录包含了用于开发、测试和构建 Grafana 插件的不同工具的首选配置。虽然您可以进行更改，但我们建议不要这样做。相反，请按照本主题中的指导来定制您的工具配置。

危险

请勿编辑 .config/ 目录或扩展工具配置。如果您尝试这样做，则可能会遇到编译失败或在 Grafana 中加载失败等问题。请按照本主题中的说明进行高级配置，而不是直接修改文件。

扩展 ESLint 配置

编辑项目根目录下的 .eslintrc 文件以扩展 ESLint 配置

示例

.eslintrc

{
  // Eslint configuration provided by @grafana/create-plugin
  "extends": "./.config/.eslintrc",
  "rules": {
    "react/prop-types": "off"
  }
}

以下示例可用于禁用弃用通知。

.eslintrc

{
  // Eslint configuration provided by @grafana/create-plugin
  "extends": "./.config/.eslintrc",
  "overrides": [
    {
      "files": ["src/**/*.{ts,tsx}"],
      "rules": {
        "deprecation/deprecation": "off"
      }
    }
  ]
}

---

扩展 Prettier 配置

编辑项目根目录下的 .prettierrc.js 文件以扩展 Prettier 配置

示例

.prettierrc.js

module.exports = {
  // Prettier configuration provided by @grafana/create-plugin
  ...require('./.config/.prettierrc.js'),
  semi: false,
};

---

扩展 Jest 配置

项目根目录下有两个属于 Jest 的文件：jest-setup.js 和 jest.config.js。

jest-setup.js: 此文件在运行测试套件中的每个测试文件之前执行。它为测试库设置 Jest DOM 并应用一些 polyfill。有关更多信息，请参阅Jest 文档。

jest.config.js: 这是扩展 Grafana 配置的 Jest 配置文件。有关更多信息，请参阅Jest 配置文档。

Jest 中的 ESM 错误

如果您在运行 Jest 或 npm run test 时看到 SyntaxError: Cannot use import statement outside a module，请参阅故障排除。

---

扩展 TypeScript 配置

编辑项目根目录下的 tsconfig.json 文件以扩展 TS 配置

示例

tsconfig.json

{
  // TypeScript configuration provided by @grafana/create-plugin
  "extends": "./.config/tsconfig.json",
  "compilerOptions": {
    "preserveConstEnums": true
  }
}

---

扩展 Webpack 配置

按照以下步骤扩展位于 .config/ 中的 Webpack 配置

1. 创建新的 Webpack 配置文件

在项目根目录中创建一个 webpack.config.ts 文件。此文件扩展了 create-plugin 提供的 Webpack 配置。

2. 将 Grafana 配置与您的自定义配置合并

使用以下 webpack-merge 命令

webpack.config.ts

import type { Configuration } from 'webpack';
import { merge } from 'webpack-merge';
import grafanaConfig from './.config/webpack/webpack.config';

const config = async (env): Promise<Configuration> => {
  const baseConfig = await grafanaConfig(env);

  return merge(baseConfig, {
    // Add custom config here...
    output: {
      asyncChunks: true,
    },
  });
};

export default config;

以下替代自定义除了“node_modules”之外，还通过规则排除了“libs”。它还提供了 Webpack v5 中不再存在的后备方案。

webpack.config.ts

import type { Configuration } from 'webpack';
import { mergeWithRules } from 'webpack-merge';
import grafanaConfig from './.config/webpack/webpack.config';

const config = async (env: any): Promise<Configuration> => {
  const baseConfig = await grafanaConfig(env);
  const customConfig = {
    module: {
      rules: [
        {
          exclude: /(node_modules|libs)/,
        },
      ],
    },
    resolve: {
      fallback: {
        crypto: require.resolve('crypto-browserify'),
        fs: false,
        path: require.resolve('path-browserify'),
        stream: require.resolve('stream-browserify'),
        util: require.resolve('util'),
      },
    },
  };
  return mergeWithRules({
    module: {
      rules: {
        exclude: 'replace',
      },
    },
  })(baseConfig, customConfig);
};

export default config;

3. 更新 package.json 以使用新的 Webpack 配置

更新 package.json 中的 scripts 以使用扩展的 Webpack 配置

package.json

-"build": "webpack -c ./.config/webpack/webpack.config.ts --env production",
+"build": "webpack -c ./webpack.config.ts --env production",
-"dev": "webpack -w -c ./.config/webpack/webpack.config.ts --env development",
+"dev": "webpack -w -c ./webpack.config.ts --env development",