# @grafana/toolkit 中文文档

规范地址：https://npmcn.com/package/%40grafana/toolkit/

版本：9\.5\.21
npm 元数据更新时间：2026-07-21T17:57:49.394Z
中文译文更新时间：2026-11-16T22:08:03.297Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40grafana/toolkit
原文对照：https://npmcn.com/package/%40grafana/toolkit/?lang=original
项目主页：https://github.com/grafana/grafana#readme
源码仓库：https://github.com/grafana/grafana

弃用说明：This package is no longer supported\. Use @grafana/create-plugin instead\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：337 kB，169 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：84 个
- 首次发布：2019-06-06T13:40:11.319Z
- 最新版本发布：2024-07-25T15:09:26.461Z
- 近 30 天下载量：14075（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：5010（近 12 个月 0 个）

## 中文简介

格拉法纳工具包

## 安装

```sh
npm install @grafana/toolkit
```

也可以使用：`pnpm add @grafana/toolkit`、`yarn add @grafana/toolkit`、`bun add @grafana/toolkit`

## README

> **@grafana/toolkit目前在BETA**。 。 。 .

# 格莱法纳工具箱

grafana-toolkit是一种能使Grafana插件得到高效开发的CLI. 我们希望帮助我们的社区关注其插件的核心价值,而不是开发插件所需的所有设置.

## 开始

设置新插件 `grafana-toolkit plugin:create` 命令 :

```sh
npx @grafana/toolkit plugin:create my-grafana-plugin
cd my-grafana-plugin
yarn install
yarn dev
```

> **说明:** 如果运行国家防范机制7+ `npx` 本条中提到的命令可以被吊起。 工作是用来 `npx --legacy-peer-deps <command to run>`。 。 。 .

## 更新您的插件以使用 grafana- toolkit

遵循下面的步骤开始在您现有的插件中使用 grafana-toolkit .

1.  添加 `@grafana/toolkit` 通过运行软件包到您的工程 `yarn add @grafana/toolkit` 或者说 `npm install @grafana/toolkit`。 。 。 .
2.  创建 `tsconfig.json` 文件在插件的根目录中并粘贴以下代码:

```json
{
  "extends": "./node_modules/@grafana/toolkit/src/config/tsconfig.plugin.json",
  "include": ["src", "types"],
  "compilerOptions": {
    "rootDir": "./src",
    "baseUrl": "./src",
    "typeRoots": ["./node_modules/@types"]
  }
}
```

3.  创建 `.prettierrc.js` 文件在插件的根目录中并粘贴以下代码:

```js
module.exports = {
  ...require('./node_modules/@grafana/toolkit/src/config/prettier.plugin.config.json'),
};
```

4.  在你身边 `package.json` 文件添加以下脚本 :

```json
"scripts": {
  "build": "grafana-toolkit plugin:build",
  "test": "grafana-toolkit plugin:test",
  "dev": "grafana-toolkit plugin:dev",
  "watch": "grafana-toolkit plugin:dev --watch"
},
```

## 使用量

使用grafana-toolkit,我们给您一个处理Grafana插件工作时执行的共同任务的CLI:

-   `grafana-toolkit plugin:create`
-   `grafana-toolkit plugin:dev`
-   `grafana-toolkit plugin:test`
-   `grafana-toolkit plugin:build`
-   `grafana-toolkit plugin:sign`

### 创建您的插件

`grafana-toolkit plugin:create plugin-name`

此命令从模板创建了新的 Grafana 插件 .

若为 `plugin-name` ,然后将模板下载到 `./plugin-name` 目录。 否则,它将被下载到目前的目录中.

### 开发您的插件

`grafana-toolkit plugin:dev`

此命令创建了一个开发架构,使用常见的浏览器工具可以轻松地玩和调试.

可用的选项 :

-   `-w`, (中文(简体) ), `--watch` - 以监视模式执行开发任务

### 测试您的插件

`grafana-toolkit plugin:test`

此命令运行 Jest 对您的密码库.

可用的选项 :

-   `--watch` - 以交互式监视模式运行测试.
-   `--coverage` - 报告代码.
-   `-u`, (中文(简体) ), `--updateSnapshot` - 执行快照更新.
-   `--testNamePattern=<regex>` - 使用与提供的regex匹配的名称进行测试([https://jestjs.io/docs/en/cli#testnamepattern-regex (中文(简体) )](https://jestjs.io/docs/en/cli#testnamepattern-regex)) (中文(简体) ).
-   `--testPathPattern=<regex>` - 使用匹配提供的正则ex的路径进行测试([https://jestjs.io/docs/en/cli#testpathpattern-regex 互联网档案馆的存檔,存档日期2014-12-22](https://jestjs.io/docs/en/cli#testpathpattern-regex)) (中文(简体) ).
-   `--maxWorkers=<num>|<string>` - 有限数目的育种工人(https://jestjs.io/docs/en/cli#-maxworkersnumstring)

### 构建您的插件

`grafana-toolkit plugin:build`

此命令创建了您的插件的制作准备 .

可用的选项 :

-   `--skipTest` - 跳过运行测试 作为建设的一部分。 如果你把建筑作为更大的管道的一部分来运行,那就很有用.
-   `--skipLint` - 跳过林丁作为建筑的一部分。 如果你把建筑作为更大的管道的一部分来运行,那就很有用.
-   `--coverage` - 在测试步骤后报告代码覆盖.
-   `--preserveConsole` - 保护控制台在代码中的语句.

### 签名插件

`grafana-toolkit plugin:sign`

此命令创建了一个签名的 MANIFEST.txt 文件, Grafana 用于验证插件的完整性 .

可用的选项 :

-   `--signatureType` - 那个 [签名类型](https://grafana.com/legal/plugins/) 您正在生成 : `private`, (中文(简体) ), `community` 或者说 `commercial`
-   `--rootUrls` - 对于私人签名,将使用插件的 Grafana 实例 URL 列表

要生成签名, 您需要注册免费账户 [https://grafana.com (中文(简体) )](https://grafana.com/),创建带有插件发布器角色的 API 密钥,并在 `GRAFANA_API_KEY` 环境变量.

## 财务问题

### 我应该用哪个版本的grafana-toolkit?

见 [Grafana 软件包版本指南](https://github.com/grafana/grafana/blob/main/packages/README.md#versioning)。 。 。 .

### Grafana-toolkit使用什么工具?

grafana-toolkit 配有 TypeScript,ESLint,Pretier,Jest,CSS和SASS支持.

### 如何开始在我的插件中使用 grafana-toolkit ?

见 [更新您的插件以使用 grafana- toolkit](https://npmcn.com/package/%40grafana/toolkit/#readme-updating-your-plugin-to-use-grafana-toolkit)。 。 。 .

### 我能使用TypeScript开发出Grafana插件吗?

没错! grafana-toolkit默认支持TypeScript.

### 我怎么测试我的插件?

grafana-toolkit 与杰斯特作为测试跑手而来.

在Grafana内部,我们使用反应测试库.

也可以通过创建来设置 Jest 与您需要的shims `jest-shim.ts` 在同一目录中的文件 : `<YOUR_PLUGIN_DIR_>/config/jest-shim.ts`

### 我能为杰斯特提供定制装置吗?

您可以提供自定义 Jest 配置 `package.json` 文档。 详情见 [记录](https://jest-bot.github.io/jest/docs/configuration.html)。 。 。 .

目前我们支持以下 Jest 配置属性:

-   [`snapshotSerializers`](https://jest-bot.github.io/jest/docs/configuration.html#snapshotserializers-array-string)
-   [`moduleNameMapper`](https://jestjs.io/docs/en/configuration#modulenamemapper-object-string-string)

### 我想用monaco编辑器, 有什么特别的我应该注意的吗?

对,有的. 我们已经在Grafana 装了摩那哥编辑器 见\[webpack配置\] (https://github. com/grafana/grafana/blob/主/标语/webpack/webpack.common.js#L49-L58. 我们用 `@monaco-editor/react` 装入器配置软件包 [https://github.com/suren-atoyan/monaco-react#loader-config 互联网档案馆的存檔,存档日期2013-12-11](https://github.com/suren-atoyan/monaco-react#loader-config) 默认情况下,monaco文件正在从CDN下载. 我们使用捆绑版. 初始化 : [https://github.com/grafana/grafana/blob/main/scripts/webpack/webpack.common.js#L49-L58t (中文(简体) )](https://github.com/grafana/grafana/blob/main/scripts/webpack/webpack.common.js#L49-L58t) 我们建议使用捆绑版来防止与版本不匹配相关的不想要的问题.

### 我如何定制Webpack规则或插件?

你可以自己提供 `webpack.config.js` 文件导出 a `getWebpackConfig` 函数。 我们建议您扩展标准配置,但您可以自行创建:

```js
const CustomPlugin = require('custom-plugin');

module.exports.getWebpackConfig = (config, options) => ({
  ...config,
  plugins: [...config.plugins, new CustomPlugin()],
});
```

### 我该怎么处理我的插件?

我们支持纯CSS、SASS和CSS-in-JS方法(通过 [情感](https://emotion.sh/)) (中文(简体) ).

#### 单一 CSS 或 SASS 文件

创建您的 CSS 或 SASS 文件并导入到插件入口( 通常情况下) `module.ts`:

```ts
import 'path/to/your/css_or_sass';
```

样式将通过 `style` 运行时标记 .

> **说明:** 将输入的静态资产作为基数64. _这将来可以改变!_

#### 主题特定样式表

如果您想要为暗/ 淡主题提供不同的样式表, 请创建 `dark.[css|scss]` 财务报告和审定财务报表 `light.[css|scss]` 文档中 `src/styles` 您的插件目录 。 grafana-toolkit 生成存储在 `dist/styles` 目录.

要让 Grafana 拿起您的主题样式表, 您需要使用 `loadPluginCss` 从 `@grafana/runtime` 软件包。 通常您会在插件的切入点 :

```ts
import { loadPluginCss } from '@grafana/runtime';

loadPluginCss({
  dark: 'plugins/<YOUR-PLUGIN-ID>/styles/dark.css',
  light: 'plugins/<YOUR-PLUGIN-ID>/styles/light.css',
});
```

您必须添加 `@grafana/runtime` 通过运行到您的插件依赖性 `yarn add @grafana/runtime` 或者说 `npm install @grafana/runtime`。 。 。 .

> **说明:** 在此情况下, 静态文件( png, svg, json, html) 当插件被捆绑时都会被复制到 dist 目录 。 这些文件的相对路径不会改变!

#### 情感

从格拉法纳6.2起 _我们建议的方法_ 用于样式插件 [情感](https://emotion.sh/)这是Grafana的CSS-in-JS图书馆 使用"情感"的最大优势在于可以访问"格拉法纳主题"变量.

要开始使用情感, 您首先必须把它添加到您的插件依赖性中 :

```
  yarn add "emotion"@10.0.27
```

然后导入 `css` 来自情感的函数 :

```ts
import { css } from 'emotion';
```

现在,你准备执行你的风格:

```tsx
const MyComponent = () => {
  return (
    <div
      className={css`
        background: red;
      `}
    />
  );
};
```

要进一步了解使用Grafana主题的情况,请参见: [主题使用指南](https://github.com/grafana/grafana/blob/main/style_guides/themes.md#react)

> 我们不支持情感 `css` 道具 (英语). 改用类名!

### 我能调整TypeScript的配置以适应我的需要吗?

没错! 不过,重要的是,你 `tsconfig.json` 文件包含以下行:

```json
{
  "extends": "./node_modules/@grafana/toolkit/src/config/tsconfig.plugin.json",
  "include": ["src"],
  "compilerOptions": {
    "rootDir": "./src",
    "typeRoots": ["./node_modules/@types"]
  }
}
```

### 我能调整ESLint的配置来适应我的需要吗?

{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}加拉法纳·托克特来了 [eSLint 默认配置](https://github.com/grafana/grafana/blob/main/packages/grafana-toolkit/src/config/eslint.plugin.json)目前,没有办法定制ESLint配置.

### Pretier如何融入grafana-toolkit工作流程??

当构建插件时 [`grafana-toolkit plugin:build`](https://npmcn.com/package/%40grafana/toolkit/#readme-building-plugin) 任务, grafana-toolkit 执行 Pretier 检查。 如果检查发现任何 Pretier 问题, 构建将不会通过 。 为了避免这种情况,我们建议开发插件 [`grafana-toolkit plugin:dev --watch`](https://npmcn.com/package/%40grafana/toolkit/#readme-developing-plugin) 任务运行。 这项任务试图自动解决Pretier问题.

### 我的编辑不尊重Pretier config, 我该怎么办?

您的编辑器需要创建 Pretier 配置 `.prettierrc.js` 在您的插件根目录中包含以下内容的文件 :

```js
module.exports = {
  ...require('./node_modules/@grafana/toolkit/src/config/prettier.plugin.config.json'),
};
```

### 我该如何添加非 npm 软件包的第三方依赖性 ?

把它们放进去 `static` 在您的工程根中设置目录。 这个 `static` 插件构建时复制目录 .

### 当我运行纱线安装时,我收到这个消息: `Request failed \"404 Not Found\"`

如果您正在使用版本 `canary`,此出错的原因是 `canary` 发布未发行的上一个版本 `yarn.lock` 过时了 删除 `yarn.lock` 运行 `yarn install` 再来一次.

### 当我运行我的插件时我收到这个消息: `Unable to dynamically transpile ES module A loader plugin needs to be configured via SystemJS.config({ transpiler: 'transpiler-module' }).`

使用插件捆绑时发生此错误 `grafana-toolkit plugin:dev` 任务和您的代码注释包括 ES2016 代码.

目前有两个问题:

-   这个 `grafana-toolkit plugin:dev` 任务不会从捆绑的软件包中删除注释.
-   格拉法纳不支持 [ES模块](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/)。 。 。 .

如果你的评论包括ES2016代码,那么SystemJS v0.20.19,Grafana在内部使用它来加载插件,将您的代码解释为无害环境管理并失败.

要纠正这个错误,请从您的评论中删除ES2016代码.

### 我想在插件中动态导入模块

创建含有此内容的 Webpack.config.js( 在根 __ 插件( 插件)

```ts
// webpack.config.js
const pluginJson = require('./src/plugin.json');
module.exports.getWebpackConfig = (config, options) => ({
  ...config,
  output: {
    ...config.output,
    publicPath: `public/plugins/${pluginJson.id}/`,
  },
});
```

插件id是插件.json文件中所写的id.

## 贡献给grafana-toolkit 游戏

可以通过帮助开发或调试来为grafana-toolkit做出贡献.

### 开发 grafana- toolkit

典型的插件应该使用 `@grafana/toolkit` 从 npm 安装。 然而,在研究工具包时,你可能想要使用本地版本. 运行本地工具包版本有两种方法:

### 使用 `NODE_OPTIONS` 装入线条 pnp 文件 :

您可以使用此命令从 grafana 仓库直接运行 grafana 工具包 .

`NODE_OPTIONS="--require $GRAFANA_REPO/.pnp.cjs" $GRAFANA_REPO/packages/grafana-toolkit/dist/bin/grafana-toolkit.js [command]`

您可以替换 `$GRAFANA_REPO` 与路径 你的草原克隆 或者把它放在你的环境下。 例如: `export GRAFANA_REPO=/home/dev/your_grafana_clone`

> 说明: 这将运行 Grafana 工具包 从您的本地克隆, 但不会改变 依赖性.

### 用纱莓连接.

#### 先决条件

对于下面的工作,要保证有一个插件,用纱莓和纱莓PnP来测试对照变化. 任意复制面板插件 [这里](https://github.com/jackw/plugin-yarn-berry) 如果需要的话.

1.  克隆 [Grafana 仓库](https://github.com/grafana/grafana)。 。 。 .
2.  导航到您克隆了 Grafana repo 到然后运行的目录 `yarn install --immutable`。 。 。 .
3.  打开 `packages/grafana-toolkit/package.json`,删除任何提及 `@grafana/data` 财务报告和审定财务报表 `@grafana/ui`。然后添加以下内容:

```
  "devDependencies": {
    "@grafana/data": "workspace:*",
    "@grafana/ui": "workspace:*"
  },
  "peerDependencies": {
    "@grafana/data": "*",
    "@grafana/ui": "*"
  }
```

**不要这样做 `package.json` 代码更改。 需要解决这些问题 `@grafana` 用于开发目的.**

4.  运行 `yarn` 在格拉法纳雷波.
5.  导航到您的插件代码所在的目录并运行 `yarn link <GRAFANA_DIR>/packages/grafana-toolkit`使用纱莓 `portal` 协议将 grafana-toolkit 软件包“链接”并解决其依赖性输入您的插件代码,允许您针对插件代码开发工具包并测试修改.
6.  对Grafana工具包作必要的修改.

### 调试 grafana 工具Kit

要调试 grafana- toolkit 您可以使用标准 [节点JS调试方法](https://nodejs.org/de/docs/guides/debugging-getting-started/#enable-inspector) (单位:千美元)`node --inspect`, (中文(简体) ), `node --inspect-brk`) (中文(简体) ).

在调试会话中运行 grafana-toolkit 使用工具包目录中的以下命令 :

`node --inspect-brk ./bin/grafana-toolkit.js [task]`

运行 [链接](https://npmcn.com/package/%40grafana/toolkit/#readme-develop-grafana-toolkit) 调试会话中的 grafana-toolkit 使用插件目录中的以下命令 :

`node --inspect-brk ./node_modules/@grafana/toolkit/bin/grafana-toolkit.js [task]`

## 常见问题

### @grafana/toolkit 是什么？

格拉法纳工具包注意：该包已被作者标记为弃用——This package is no longer supported\. Use @grafana/create-plugin instead\.

### 如何安装 @grafana/toolkit？

在项目目录运行 npm install @grafana/toolkit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 grafana-toolkit，可以用 npx grafana-toolkit 直接运行。

### @grafana/toolkit 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/grafana\_\_toolkit 是否存在。

### @grafana/toolkit 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @grafana/toolkit 可以商用吗？

@grafana/toolkit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @grafana/toolkit 的下载量有多少？

根据 npm 官方下载统计，@grafana/toolkit 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,075 次，日均约 469 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @grafana/toolkit 还在维护吗？

最新版本 9\.5\.21 发布于 2024/07/25（2 年前）；至今共发布 5010 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/06/06。作者已将其标记为弃用，新项目建议寻找替代方案。

