故障排除

如果您在使用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。

注意

如果您使用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。
• 在您的项目中使用 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 电脑的用户。如果您之前为使用create-plugin（v1.12.2 之前的版本）构建的插件构建了镜像，那么如果旧镜像未被删除，运行docker compose up可能会失败并显示上述消息。

您可以执行以下操作：

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