跳到主内容

故障排除

在使用 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 Subsystem for 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。您可以在微软的文档中找到安装指南。我们建议安装 Node.js 的最新 LTS 版本。

我已经在 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。
  • 您可以按照微软的指南来正确安装 Node.js。
注意

如果您使用 sudo apt install nodejs 安装了 Node.js，而没有遵循任何指南或更改 APT 仓库，则很可能没有使用最新的 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。
  • 在您的项目中使用带 poll 的 webpack watchOption。有关如何扩展 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 电脑用户。如果您之前使用 create-plugin 在 v1.12.2 之前为插件搭建了镜像，并且旧镜像未被移除，那么运行 docker compose up 可能会出现上述错误消息。

您可以尝试以下操作：​

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