跳到主要内容

问题排查

如果您在使用 create-plugin 或 sign-plugin 工具时遇到问题，可以尝试和检查以下事项。

我收到错误信息：Unsupported operating system 'Windows' detected. Please use WSL with create-plugin​

create-plugin 工具不支持原生 Windows。如果您使用的是 Windows，则必须安装 WSL 2 才能使用 create-plugin。WSL 2 是 Windows Linux 子系统架构的新版本，允许您在 Windows 上运行 ELF64 Linux 二进制文件。

我正在使用带有 WSL 的 Windows，但仍然收到错误信息：Unsupported operating system 'Windows' detected.​

请确保您正在使用 WSL 终端。仅仅在 Windows 上安装 WSL 是不够的；您需要设置您的 WSL 环境。

要检查您是否正在使用 WSL 终端，请运行以下命令：uname -a。此命令应返回类似以下内容：

Linux ....-microsoft-standard-WSL2 #... GNU/Linux

如果您收到错误或不同的输出，则说明您没有使用 WSL 终端。

我可以确认我在 WSL 终端内，但仍然收到错误信息：Unsupported operating system 'Windows' detected.​

您必须在 WSL 环境中安装 Node.js。您可以在 Microsoft 的文档中找到有关如何安装它的指南。我们建议安装最新 LTS 版本的 Node.js。

我在 WSL 中安装了 Node.js，但仍然收到错误信息：Unsupported operating system 'Windows' detected.​

可能是您在 WSL 中安装了 Node.js，但您没有使用最新的 LTS 版本。此外，WSL 存在一个问题，它可能会拾取 Windows 二进制文件并尝试运行它们。这意味着即使您在 WSL 终端内，您仍然可能正在运行 create-plugin 不支持的 Windows 二进制文件。

您可以这样做：​
  • 通过运行 node --version 检查您是否正在使用 Node.js 版本 18 或更高版本。
  • 通过运行以下命令检查您是否正在使用 Node.js 和 npx 的 Linux 二进制文件：which node 和 which npx（请注意，命令是 which，而不是 node --version）。您应该收到类似于 /usr/bin/node 和 /usr/bin/npx 的输出。如果这些命令的输出类似于 ..../Program Files/nodejs/npx，则意味着您正在使用错误的二进制文件，应该安装或重新安装 Node.js。
  • 您可以按照 Microsoft 指南了解如何正确安装 Node.js。
注意

如果您在没有遵循任何指南或更改 APT 存储库的情况下使用 sudo apt install nodejs 安装了 Node.js，则您可能没有使用最新的 Node.js LTS。

当我使用新创建的插件打开 Grafana 时，Grafana 无法加载插件。​

  • 首先，尝试重启 Grafana 以确保它检测到新插件。
  • 如果您使用的是原生 Windows（没有 WSL），则需要使用 WSL。create-plugin 工具不支持原生 Windows。

当我在插件中运行 npm run build 或 npm run dev 时，我看不到我的更改被反映出来。​

如果您使用挂载来访问您的文件，则 webpack 很可能无法检测到您的文件更改。跨 WSL 和 Windows 文件系统处理文件存储和性能可能会有问题。此问题与 create-plugin 无关，而是 WSL 和 Windows 的运行方式。

您可以这样做：​

  • 如果您正在从原生 Windows 应用程序（例如 VS Code）编辑代码，则每次想要在插件中看到更改时，都需要手动重新运行 yarn build。
  • 在您的项目中使用 webpack watchOption 和 poll。在我们的文档中查找有关如何扩展 webpack 配置的说明。

当运行 Jest 或 npm run test 时，我收到错误信息：SyntaxError: Cannot use import statement outside a module。​

当前 Jest 配置的一个常见问题是导入仅提供 ESM 构建的 npm 包。这些包会导致 Jest 报错：SyntaxError: Cannot use import statement outside a module。

为了解决这个问题，我们提供了一个已知包列表，以传递给 [transformIgnorePatterns](https://jest.node.org.cn/docs/configuration#transformignorepatterns-arraystring) Jest 配置属性。

如有必要，可以按以下方式扩展它

process.env.TZ = 'UTC';
const { grafanaESModules, nodeModulesToTransform } = require('./.config/jest/utils');

module.exports = {
  // Jest configuration provided by @grafana/create-plugin
  ...require('./.config/jest.config'),
  // Inform Jest to only transform specific node_module packages.
  transformIgnorePatterns: [nodeModulesToTransform([...grafanaESModules, 'packageName'])],
};

在运行 docker compose up 或 npm run server 后，我收到错误信息："image with reference <plugin-name> was found but does not match the specified platform: wanted linux/amd64, actual: linux/arm64/v8"。​

此错误最有可能影响使用 Apple 芯片的 Mac 电脑的用户。如果您之前为 v1.12.2 之前使用 create-plugin 搭建的插件构建了镜像，则如果旧镜像尚未删除，运行 docker compose up 可能会失败并显示上述消息。

您可以这样做：​

  • 运行 docker compose down 以停止并删除容器。
  • 使用 docker rmi <plugin-name> 删除镜像。
  • 运行 docker compose up 或 npm run server。