将 Grafana 插件迁移到 React 19…

当需要让 Grafana 插件兼容 React 19（Grafana 13）时，按顺序执行检测、脚手架更新、依赖升级与源码修复，全部改动放在一个 PR 中。

适用场景

解决思路

1. 检测插件上下文：用 shell 命令定位 plugin.json 与 package.json（src/ 或 plugin/ 下），用 jq 读取 PLUGIN_ID，根据 yarn.lock/pnpm-lock.yaml 判断包管理器 PM，读取 .config/.cprc.json 的 CP_VERSION；若 PLUGIN_ID 为空则向用户询问插件根路径。
2. 扫描兼容性问题：先运行 `npm run build 2>&1 | tail -5`，再运行 `npx -y @grafana/react-detect@latest 2>&1` 并保存输出；若构建失败（插件从未构建过）则跳过此步，改在 Step 9 之后再运行 react-detect；即使输出为 “No breaking changes detected” 也继续，因为 jsx-runtime 外部化与 grafanaDependency 升级始终必需；Step 9 后需再次运行 react-detect 确认问题全部解决。
3. 更新 @grafana/create-plugin：确保 git 工作区干净（必要时先建 feature 分支），运行 `npx @grafana/create-plugin@latest update 2>&1`；若 `yarn install` 报 “engine is incompatible”，手动执行 `yarn install --ignore-scripts --ignore-engines 2>&1 | tail -10`，提交中间状态（`git add -A && git commit -m "chore: intermediate create-plugin update" --no-verify`）后重跑 update；若 ESLint 9 迁移（004）因 parser 错误失败，不要跳过，先提交已成功部分（commit message 用 "chore: update create-plugin (ESLint 9 migration manual)"），再按 ESLint 9 章节手动完成；更新后运行 `yarn install --ignore-scripts --ignore-engines 2>&1 | tail -10` 和 `cat .config/.cprc.json` 验证，有变更则提交 "chore: update create-plugin scaffolding"。
4. 完成 ESLint 9 迁移：用 `ls eslint.config.js .eslintrc* .config/.eslintrc* 2>/dev/null` 和 `npx eslint --version 2>&1` 检查状态；场景 A（eslint.config.js 存在且 yarn lint 通过）直接继续；场景 B（存在但 lint 失败）查看 `yarn lint 2>&1 | head -30`，若报 `Invalid option '--ignore-path'` 或 `--ext'` 则从 package.json 的 lint 脚本移除这些 flag 改为 `eslint --cache .`，若报 `Cannot find module 'eslint-plugin-deprecation'` 则从 eslint.config.js 移除该引用（由 @typescript-eslint/no-deprecated 替代），其他已删除插件的死引用也一并移除；场景 C（无 eslint.config.js）先检查 `ls node_modules/@grafana/eslint-config/flat.js`，存在则以它为 base 创建 eslint.config.js（import grafanaConfig from '@grafana/eslint-config/flat'; export default [...grafanaConfig, { ignores: ['**/dist/', '**/node_modules/', '**/.config/', '**/coverage/'] }]），并把旧 .eslintrc 的自定义规则迁移为数组中的额外配置对象，更新 lint 脚本为 `"lint": "eslint --cache ."`，删除根目录 .eslintrc（保留 .config/.eslintrc）；最后 `yarn lint 2>&1 | tail -20` 验证，用 `yarn lint --fix` 修复可自动修复项，提交 "chore: complete ESLint 9 flat config migration"。
5. 外部化 jsx-runtime：确保 git 工作区干净，运行 `npx @grafana/create-plugin@latest add externalize-jsx-runtime 2>&1`；用 `grep "jsx-runtime" .config/bundler/externals.ts 2>/dev/null` 验证，找到则提交并继续；未找到说明命令失败，此时才手动在根 webpack.config.ts 添加 `externals: ['react/jsx-runtime', 'react/jsx-dev-runtime']`；提交 "feat: externalize jsx-runtime"。
6. 升级 grafanaDependency：用 `jq -r '.dependencies.grafanaDependency' $PLUGIN_JSON` 查看，若未达到 `>=12.3.0` 则更新（Step 3 的 create-plugin add 可能已完成）。
7. 升级依赖：若存在 @grafana/faro 包，将 @grafana/faro-react 与 @grafana/faro-web-sdk 升到 ^2.2.3、@grafana/faro-web-tracing 升到 ^2.0.0；将 @grafana/data、@grafana/runtime、@grafana/schema、@grafana/ui 升到 ^12.2.0 或更高，若插件使用翻译或 @grafana/scenes 需要则添加 @grafana/i18n@^12.2.0；将 react 与 react-dom 升到 ^18.3.0（提前暴露 React 19 问题），若缺失则把 @types/react@^18.3.0 和 @types/react-dom@^18.3.0 加入 devDependencies；从 devDependencies 移除 eslint-plugin-deprecation（由 @typescript-eslint/no-deprecated 替代）和 @types/testing-library__jest-dom（由 setupTests.d.ts 替代）；若 yarn install 因过期 git 引用失败，不要编辑 yarn.lock，而是在 package.json 添加 resolutions 条目（"<package-name>": "<working-version-or-git-ref>"），然后 `rm -rf node_modules yarn.lock` 并 `yarn install --ignore-engines 2>&1 | tail -10`。
8. 修复未满足的 @openfeature/web-sdk peer 依赖：用 `yarn --version 2>&1 | head -1` 检查是否为 yarn classic（以 1. 开头），若是则运行 `yarn install --ignore-engines 2>&1 | grep "unmet peer dependency.*openfeature/web-sdk"`，若发现警告则执行 `yarn add -D @openfeature/web-sdk @openfeature/core --ignore-engines`；Yarn v2+ 或 npm v7+ 可跳过（peer 依赖会自动安装）。
9. 修复源码问题：用 grep 扫描 src/ 下的 ReactDOM.render/unmountComponentAtNode/findDOMNode、.defaultProps=、.propTypes=、contextTypes/getChildContext、createFactory、ChangeEvent<HTMLInputElement>；对应修复：ReactDOM.render() 改为 createRoot(container).render(element)；函数组件的 defaultProps 改为解构参数默认值；类组件的 defaultProps 保留（仍可用）；propTypes 删除；contextTypes/getChildContext 改用 React.createContext() + useContext()；createFactory 改用 JSX 或 createElement()；checkbox 上的 ChangeEvent<HTMLInputElement> 改为 FormEvent<HTMLInputElement>。
10. 构建、类型检查、测试：运行 `rm -rf node_modules dist`、`yarn install --ignore-engines 2>&1 | tail -10`、`yarn build 2>&1 | tail -10`、`yarn typecheck 2>&1 | tail -10`、`yarn test --watchAll=false 2>&1 | tail -10`；按错误对照修复：Cannot find module 'react/jsx-runtime' → 重跑 Step 4 的 create-plugin add；Cannot find module '@openfeature/web-sdk' → `yarn add -D @openfeature/web-sdk @openfeature/core`；Can't resolve '@grafana/i18n' → `yarn add @grafana/i18n@^12.2.0`；Cannot read properties of undefined (reading 'ReactCurrentOwner') → 升级 @grafana-cloud/* 包；图标按钮报 aria-label is missing → 添加 aria-label 属性；yarn.lock 中 git hash 过期 → 在 package.json 添加 resolutions、删除 lockfile 后重装；详细已知问题（i18n 崩溃、@grafana/schema 类型破坏、publicPath 不匹配）见 references/known-issues.md。
11. 更新 CI（如适用）：用 `grep -rn "plugin-ci-workflows\|e2e-version" .github/workflows/ 2>/dev/null` 检查；若为 plugin-ci-workflows@main 或 >= 6.0.0 则已测试 React 19，无需改动；若为 plugin-actions/e2e-version 则添加 `skip-grafana-react-19-preview-image: false`；两者都没有则用 `GRAFANA_VERSION=dev-preview-react19 docker compose up --build` 手动测试。
12. 压缩并推送：运行 `git reset --soft origin/main`、`git add -A`、`git commit -m "fix: Prepare plugin for React 19 compatibility"`；commit message 正文列出 create-plugin 版本变更、ESLint 9 迁移、关键依赖升级和源码修复。
13. 参考资源：迁移指南（grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/migrate-12_x-to-13_x）、React 19 插件开发者博客、React 19 changelog、grafana-collector-app #1337 PR、grafana/scenes issues（上游 i18n 跟踪）。

适用边界 · 注意事项

• 不要将 React 升级到 19，只做前向兼容改动。
• 不要手动编辑 yarn.lock。
• 若插件尚未构建过导致 Step 2 构建失败，应跳过该步并在 Step 9 之后再运行 react-detect。