设置您的开发环境

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

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

Docker 开发环境

create-plugin 工具 包含一个开发环境，其中包含 Docker。它允许您启动一个 Grafana 应用程序的实例，供插件开发者在其中进行编码。

info

在开发过程中，没有必要 签署插件。使用 @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://127.0.0.1:3000 上运行的 Grafana 开发服务器。

配置 Grafana 版本

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

npm

GRAFANA_VERSION=10.0.0 npm run server

pnpm

GRAFANA_VERSION=10.0.0 pnpm run server

yarn

GRAFANA_VERSION=10.0.0 yarn run server

配置 Grafana 镜像

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

docker-compose.yaml

version: '3.7'

services:
  grafana:
    container_name: 'myorg-basic-app'
    build:
      context: ./.config
      args:
        grafana_version: ${GRAFANA_VERSION:-9.1.2}
        grafana_image: ${GRAFANA_IMAGE:-grafana}

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

调试后端插件

如果您正在开发具有后端部分的插件，请使用 DEVELOPMENT=true 运行 npm run server。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>"
        }
      ]
    }
  ]
}

您可以在 docker compose 中通过设置 GO_VERSION 和 GO_ARCH 环境变量来控制用于构建插件的 go 版本和架构

docker-compose.yaml

version: '3.7'

services:
  grafana:
    container_name: 'myorg-basic-app'
    build:
      context: ./.config
      args:
        GO_VERSION: ${GO_VERSION:-1.22}
        GO_ARCH: ${GO_ARCH:-amd64}

您还会注意到 docker-compose.yaml 文件中也包含以下设置

docker-compose.yaml

    security_opt:
      - "apparmor:unconfined"
      - "seccomp:unconfined"
    cap_add:
      - SYS_PTRACE

它们对于允许 delve 附加到正在运行的进程并对其进行调试是必要的，不应在生产环境中使用。

设置 GitHub 工作流程

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

CI 工作流程

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

发布工作流程

发布 (release.yml) 工作流程旨在构建、测试、打包和签署您的插件，以便您随时发布新版本。这会自动执行在 GitHub 中创建发布的过程，并提供有关将插件提交到 Grafana 插件目录的说明。

warning

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

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

1. 访问存储库设置

• 转到您的 GitHub 存储库。
• 导航到“设置”选项卡。

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@release
        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)

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

工作流程包含以下步骤

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

扩展配置

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

danger

不要编辑 .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 配置

要扩展 TS 配置，请编辑项目根目录中的 tsconfig.json 文件

示例

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",