企业官网建设流程全解析

awesome-copilot 中的 React 18 迁移指挥家：React 16/17 类组件代码库到 18.3.1 的编排式升级实战

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

本篇文章以 awesome-copilot 仓库中 react18-commander.agent.md 这份 Agent 规格说明为骨架，系统讲解如何用“编排式多 Agent 流水线”把 React 16/17 的类组件重代码库安全迁移到 React 18.3.1。你将掌握：为什么精确锁定 18.3.1 而非最新 18.x、五阶段门禁流水线如何运作、基于 memory 的可断点续跑协议、三大不安全生命周期方法与自动批处理（automatic batching）的深层修复原理，以及最终验收如何把控制台告警清零，为后续 React 19 迁移铺平道路。仓库配套的五个子 Agent 规格（react18-auditor、react18-dep-surgeon、react18-class-surgeon、react18-batching-fixer、react18-test-guardian）与 react18-upgrade 插件 都围绕同一流水线设计，可作为实战中的深度参考。

迁移指挥官：一份工作流编排规格，而不是普通提示词

react18-commander是 awesome-copilot 仓库中以“主控编排”为定位的 Agent 规格，前端数据见 agents/react18-commander.agent.md 的 YAML front-matter：它声明自己是React 16/17 → 18.3.1 迁移的主编排者（Master orchestrator），专为类组件为主（class-component-heavy）的代码库设计，并明确列出了自身工具集与可调用的子 Agent 清单：

• tools：agent、vscode/memory、edit/editFiles、execute/getTerminalOutput、execute/runInTerminal、read/terminalLastCommand、read/terminalSelection、search、search/usages、read/problems——即它既能调度子 Agent，又能直接读终端、做全文搜索、改文件，最终验收由它亲自跑。
• agents：react18-auditor、react18-dep-surgeon、react18-class-surgeon、react18-batching-fixer、react18-test-guardian——五个专用子 Agent 分别覆盖审计、依赖、类组件手术、批处理修复、测试守卫。
• argument-hint：Just activate to start the React 18 migration.——用户只需一句触发语即可启动整个流水线。

从这一编排结构看，这份文档的实质是一份“可执行的迁移作战计划”：它不是罗列迁移知识点，而是把一次大型重构拆成五个顺序执行、逐门门禁放行的阶段，由统一的主控负责状态记账与断点续跑。插件侧 plugins/react18-upgrade/README.md 印证了这一家族化设计：该插件打包了 6 个 Agent 与 7 个专项 skill（react-audit-grep-patterns、react18-batching-patterns、react18-dep-compatibility、react18-enzyme-to-rtl、react18-legacy-context、react18-lifecycle-patterns、react18-string-refs等），可用copilot plugin install react18-upgrade@awesome-copilot安装后整组使用。

为什么偏偏是 18.3.1？

整份规格反复强调一个战略定位：18.3.1 是 React 19 迁移的前置哨兵版本。理由非常具体：

React 18.3.1 被发布出来的目的，就是对每个 React 19 将要移除的 API 显式地发出告警。一段在 18.3.1 下零告警跑通的代码，就是可直接交给 React 19 迁移管弦乐队的代码库。

因此这里采用的是精确锁版（exact pin）react@18.3.1+react-dom@18.3.1，而不是^18或latest。把“升到 18 最新”改成“升到 18.3.1 这个具名检查点”，本质上是把一个混沌的升级动作变成一个可验证、可交接的里程碑：任何仍然存在的废弃 API 调用都会在构建/运行期以警告形式显形，而警告就是 React 19 的“地雷清单”。

记忆协议与启动序列：让迁移可以被中断、被恢复

Memory 状态机

大型迁移几乎必然跨越多个会话。Commander 用仓库级 memory 记录迁移状态，每次启动先读、每个门禁通过后写：

#tool:memory read repository "react18-migration-state" #tool:memory write repository "react18-migration-state" "[state JSON]"

标准状态结构如下（这是门禁放行的唯一事实来源）：

{ "phase": "audit|deps|class-surgery|batching|tests|done", "reactVersion": null, "auditComplete": false, "depsComplete": false, "classSurgeryComplete": false, "batchingComplete": false, "testsComplete": false, "consoleWarnings": 0, "testFailures": 0, "lastRun": "ISO timestamp" }

phase字段的六种取值恰好一一对应五阶段流水线加一个done终态；五个布尔标记分别对应每个阶段的“门禁已通过”。会话中途断掉后，下一次激活只要读 memory 就能从第一个未完成阶段继续，不重复执行已完成阶段。同样的记忆策略贯穿所有子 Agent：auditor 写react18-audit-progress、dep-surgeon 写react18-deps-state、class-surgeon 按每个文件写react18-class-surgery-progress检查点、batching-fixer 写react18-batching-progress、test-guardian 写react18-test-state。子 Agent 级的细粒度记忆是主控级记忆的支撑——例如 class-surgeon 每改完一个文件就记录completed:[filename]:[patterns-fixed]，即使中途断线也不必重新扫一遍已完成文件。

Boot Sequence：先诊断再进场

Commander 每次启动按固定顺序执行：

1. 读 memory，向用户汇报哪些阶段已完成；
2. 探测当前 React 版本：

   node -e "console.log(require('./node_modules/react/package.json').version)" 2>/dev/null || grep '"react"' package.json | head -3

3. 已在 18.3.x→ 跳过依赖阶段，直接从 class-surgery 开始；
4. 仍在 16.x/17.x→ 从 audit 阶段开始。

这套启动逻辑保证了迁移“只做未做之事”：版本探测决定起点，memory 决定续跑位置，两者组合即可在任何时刻安全恢复。

五阶段门禁流水线：Audit → Deps → Class Surgery → Batching → Tests

每个阶段由 Commander 用#tool:agent唤醒对应子 Agent，传给它完整上下文；子 Agent 完成工作后返回结构化结论；只有门禁条件（Gate）满足，才允许推进到下一阶段并写 memory。整条链路上，任何一环不合格都不会带病进入下一步。

PHASE 1 - Audit：读遍一切，先不改任何代码

Commander 把任务下发给react18-auditor（“Deep-scan specialist”），要求它全面扫描 React 18 迁移问题点，聚焦：不安全生命周期方法、遗留 Context、字符串 ref、findDOMNode、ReactDOM.render、事件委托假设、自动批处理漏洞，以及一切会被 18.3.1 警告的模式，并把完整报告写入.github/react18-audit.md，按类别返回问题计数。

auditor 的规格把“读代码”拆成可复现的 grep 战役（详见 agents/react18-auditor.agent.md），值得直接抄进你自己的审计流程：

• PHASE 0 代码库画像：统计源码文件总数、类组件数、函数组件数、当前 React 版本，用“类组件 / 函数组件比例”预估工作量；
• PHASE 1 不安全生命周期：分别 grepcomponentWillMount、componentWillReceiveProps、componentWillUpdate（排除UNSAFE_前缀与测试文件），同时查UNSAFE_component判断是否已做过部分迁移；
• PHASE 2 批处理漏洞：找出async类方法中的多处setState、setTimeout/Promise回调里的setState、原生事件处理器里的setState——并特别标注“await 之后读取 this.state”的危险模式；
• PHASE 3 遗留 Context：childContextTypes、contextTypes、getChildContext、this.context；
• PHASE 4 字符串 ref：ref="..."与this.refs.；
• PHASE 5 findDOMNode：findDOMNode/ReactDOM.findDOMNode；
• PHASE 6 Root API：ReactDOM.render、ReactDOM.hydrate、unmountComponentAtNode；
• PHASE 7 事件委托：document.addEventListener/removeEventListener（特别是监听 click、keydown、focus、blur 且与 React 合成事件重叠者）；
• PHASE 8 StrictMode 状态：是否启用过StrictMode——没用过则告警从未暴露，命中数会很大；
• PHASE 9 依赖兼容性：用npm ls抓 peer 冲突，并核对各库对 React 18 的最低要求；
• PHASE 10 测试文件审计：遗留 render、手动假定时钟、react-dom/test-utils导入、Enzyme 使用情况。

auditor 的产出报告模板是一个分级清单：🔴 静默运行时破坏者（批处理漏洞、Enzyme）、🟠 不安全生命周期、🟡 遗留 Root API 与废弃 API、🔵 事件委托审计、📦 依赖问题，最后是 15 步的“Ordered Migration Plan”、需改动文件清单与各类别总计。仓库中相应 skill（如skills/react-audit-grep-patterns目录下的参考文档）把其中部分 grep 模式沉淀成了可复用资产。

Gate（阶段门槛）：.github/react18-audit.md存在且类别填充完整。Memory 写入：{"phase":"deps","auditComplete":true}。

PHASE 2 - Dependency Surgery：精确锁版并拦截 Enzyme

依赖阶段由react18-dep-surgeon执行，其硬性要求是精确锁版（详见 agents/react18-dep-surgeon.agent.md）：

# 精确锁版——不是 ^18，不是 latest npm install --save-exact react@18.3.1 react-dom@18.3.1 # 验证 node -e "const r=require('react'); console.log('React:', r.version)" node -e "const r=require('react-dom'); console.log('ReactDOM:', r.version)"

阶段前的硬阻断检查是 Enzyme：Enzyme 没有 React 18 适配器。一旦在package.json或依赖树里发现enzyme，dep-surgeon不得继续升级 React，而是回报BLOCKED - Enzyme detected. react18-test-guardian must rewrite all Enzyme tests to RTL first——因为在 Enzyme 存在时安装 React 18，会让全部 Enzyme 测试以无解的方式失败。

配套依赖升级基线（仓库规格明确列出的版本要求）：

v5 路由器属于需要单独决策的升级：v5 → v6 是整体 API 重构（hooks、嵌套路由全变），规格的处理方式是停住并上报 Commander——由指挥官决定是单独排一期路由器迁移，还是先用带 React 18 peer 变通方案的react-router-dom@^5.3.4（配合--legacy-peer-deps，但必须留档说明原因）。

冲突解决纪律很明确：绝不用--force；--legacy-peer-deps仅在“该包尚未发布 React 18 兼容版本”时允许且必须记录原因。阶段收尾做干净重装 + 校验：

rm -rf node_modules package-lock.json npm install npm ls 2>&1 | grep -E "WARN|ERR|peer" | wc -l # 期望 0

子 Agent 最终向 Commander 返回GO / NO-GO：GO 需同时满足react@18.3.1（精确）、react-dom@18.3.1（精确）、@testing-library/react@14.x、npm ls零 peer 错误、无 Enzyme；NO-GO 的典型触发条件包括 Enzyme 仍存在（硬阻断）、版本不等于 18.3.1、peer 错误未清。

Gate：GO +react@18.3.1确认 + 0 peer 错误。Memory 写入：{"phase":"class-surgery","depsComplete":true,"reactVersion":"18.3.1"}。

PHASE 3 - Class Component Surgery：语义迁移，而不是贴 UNSAFE_ 膏药

类组件手术是整个流水线的重头，执行者是react18-class-surgeon，其任务清单覆盖八类模式。关键方法论在规格中被反复强调：不要只加UNSAFE_前缀敷衍——那只是消音，不是修复，React 19 还得再返工。要做真正的语义迁移。

三大不安全生命周期方法（选择正确的落点）

Commander 交给 class-surgeon 的迁移映射是：

• componentWillMount→componentDidMount（副作用）或constructor（初始化 state/依据 props 推导初始 state）；
• componentWillReceiveProps→纯推导用getDerivedStateFromProps，有副作用/异步用componentDidUpdate；
• componentWillUpdate→ 需要先读 DOM 用getSnapshotBeforeUpdate（配componentDidUpdate(prevProps, prevState, snapshot)消费快照），纯副作用则挪进componentDidUpdate。

例如依据 props 变化触发异步拉取的经典迁移（规格原文模式）：

// Before：componentWillReceiveProps componentWillReceiveProps(nextProps) { if (nextProps.userId !== this.props.userId) { this.setState({ userData: null, loading: true }); fetchUser(nextProps.userId).then(data => this.setState({ userData: data, loading: false })); } } // After：componentDidUpdate（副作用必须放这里） componentDidUpdate(prevProps) { if (prevProps.userId !== this.props.userId) { this.setState({ userData: null, loading: true }); fetchUser(this.props.userId).then(data => this.setState({ userData: data, loading: false })); } }

注意语义细节：componentWillReceiveProps(nextProps)比较的是“即将到来的新 props 与当前 props”，而componentDidUpdate只能拿到prevProps，因此比较方向要翻转。而纯状态派生则要求走static getDerivedStateFromProps——但规格特别警示：它在每次 render 都会触发（不只 props 变化时），必须把前值存进 state 做 diff，否则会陷入无限派生循环：

static getDerivedStateFromProps(props, state) { if (props.items !== state.prevItems) { return { sortedItems: sortItems(props.items), prevItems: props.items, }; } return null; } // 同时在 constructor 里初始化 this.state = { ..., prevItems: props.items }

其余五类 API 迁移

• 遗留 Context（contextTypes/childContextTypes/getChildContext）→createContext：这是跨文件迁移——必须先找到 provider 及其所有 consumer。Provider 侧把getChildContext()返回的对象变成<ThemeContext value={...}>；类 consumer 侧用单数static contextType = ThemeContext替换复数contextTypes。
• 字符串 ref（ref="myInput"+this.refs.myInput）→React.createRef()：constructor 中创建this.myInputRef = React.createRef()，JSX 写作ref={this.myInputRef}，访问改为this.myInputRef.current。
• findDOMNode→ 直接 ref：不再ReactDOM.findDOMNode(this)拿 DOM 节点，而是把ref挂到组件根元素上直接持有节点引用。
• ReactDOM.render→createRoot：迁移入口文件src/index.js/main.js，这是开启自动批处理与 React 18 特性的前提——停留在遗留 root 上的应用拿不到批处理修复：

// Before import ReactDOM from 'react-dom'; ReactDOM.render(<App />, document.getElementById('root')); // After import { createRoot } from 'react-dom/client'; const root = createRoot(document.getElementById('root')); root.render(<App />);

• ReactDOM.hydrate→hydrateRoot：SSR 场景同理。

class-surgeon 的执行纪律（见 agents/react18-class-surgeon.agent.md 的 Execution Rules）：一次只处理一个文件、每文件全量迁移完再进下一个、每文件写 memory 检查点、绝不触碰测试文件、保留全部业务逻辑/注释/Emotion 样式/Apollo hooks。阶段完成用四组 grep 自检清零（不安全生命周期=0、遗留 context=0、this.refs=0、ReactDOM.render=0）。

Gate：源码中废弃模式清零 + 构建成功。Memory 写入：{"phase":"batching","classSurgeryComplete":true}。

PHASE 4 - Automatic Batching Surgery：处理“最阴险的静默运行时破坏者”

批处理阶段交给react18-batching-fixer。之所以是“最阴险的破坏”，因为没有警告、没有报错，只是状态行为变了。规格用并排对照把新旧世界差异讲得极清楚：

// React 17（旧世界）——async/setTimeout 中的 setState 立即重渲染 this.setState({ loading: true }); // → 立即 re-render，this.state.loading === true const data = await fetchData(); if (this.state.loading) { // ← 读到的已是更新后的值 this.setState({ data, loading: false }); } // React 18（新世界）——Promise/setTimeout/原生事件里也自动批处理 this.setState({ loading: true }); // → BATCHED，没有立即 re-render const data = await fetchData(); if (this.state.loading) { // ← 仍是 false！条件静默失败，后续 setState 永不执行 this.setState({ data, loading: false }); // ← never called } // 所有 setState 在最后一次性 flush

类组件中“异步取数 → setState → 条件 setState”这类状态链在 18 下必然出错。修复决策被规格提炼为一张分诊表，这是本阶段最值得记住的判断准则：

flushSync的用法（从react-dom导入，不是react-dom/client）：

import { flushSync } from 'react-dom'; async processOrder() { flushSync(() => this.setState({ status: 'loading' })); // 强制先渲染一步 await validateOrder(); flushSync(() => this.setState({ status: 'processing' })); // 再渲染一步 await processPayment(); this.setState({ status: 'done' }); // 最后一步无需 flushSync }

默认偏好是先重构、慎用 flushSync——只有 UI 行为在语义上依赖中间渲染时才动用后者。阶段尾声向.github/react18-audit.md追加“Automatic Batching Fix Status”段（审查方法数、flushSync 插入数、纯重构数、转交 test-guardian 的测试模式数）。

Gate：Agent 确认批处理审计完成，无运行时状态顺序 bug。Memory 写入：{"phase":"tests","batchingComplete":true}。

PHASE 5 - Test Suite Fix & Verification：跑到零失败为止

测试阶段由react18-test-guardian兜底。由于批处理行为改变和 RTL v14 的 API 变化，旧测试大面积失败是常态，规格明确“不跑到零失败不罢休”。测试失败可按类型分诊（详见 agents/react18-test-guardian.agent.md 的 Triage Table）：

其中三条 React 18 测试语义值得展开：

1. 异步 act：React 18 对异步更新的 act 更严格，同步act(() => { fireEvent.click(...) })之后立即断言中间态会失败，需改await act(async () => {...})，或直接用 RTL 内置异步工具waitFor/findBy*（它们内部已包 act）。
2. 批处理回归测试：任何“fireEvent 后紧跟基于状态的同步 expect（无 waitFor）”都是候选问题，中间态断言必须改await waitFor(...)。
3. StrictMode 双调用：React 18 开发模式会双调用 render、useState/useReducer 初始化、useEffect cleanup+setup、类构造函数与 render，测试若断言“被调用 N 次”会翻车——规格的策略是不要猜，跑一遍取真实次数再更新。另一个常见修复是userEvent.setup()+await user.click()的 v14 异步写法。

若项目存在自定义 render helper（如renderWithProviders、customRender），需确认其底层是 RTL v14 的render（内部已走createRoot），并示范了用<MockedProvider mocks={mocks}>包 wrapper 的 React 18 兼容写法。执行循环上，先跑全量拿失败清单、按类别分组、逐文件修复并单文件重跑直至全绿。

Gate：npm test→ 0 failures、0 errors。Memory 写入：{"phase":"done","testsComplete":true,"testFailures":0}。

最终验收门禁：Commander 亲自执行

第五阶段结束后，Commander 不再假手他人，直接在终端跑验收脚本：

echo "=== BUILD ===" npm run build 2>&1 | tail -20 echo "=== TESTS ===" npm test -- --watchAll=false --passWithNoTests --forceExit 2>&1 | grep -E "Tests:|Test Suites:|FAIL" echo "=== REACT 18.3.1 DEPRECATION WARNINGS ===" npm run build 2>&1 | grep -i "warning\|deprecated\|UNSAFE_" | head -20

只有在以下三个条件同时满足时才允许宣告 COMPLETE ✅：构建退出码为 0、测试 0 失败、构建输出中无任何 React 弃用警告。若告警仍残留——按规格的比喻，那些是React 19 的地雷——必须带着具体警告文本重新唤醒react18-class-surgeon再次处理，直到清零。

为什么 16/17 → 18 比 18 → 19 更难

规格单列一节解释这一反直觉结论，四类“沉默工作了很多年”的模式正是难点所在：

• 自动批处理是头号静默运行时破坏者：16/17 中 Promise、setTimeout 里的 setState 会立即触发重渲染，18 起统一批处理。类组件中“异步取数 → setState → 条件 setState”的链式逻辑必然出错，且无警告无声失败。
• 遗留生命周期方法在非 StrictMode 下从不报错：componentWillMount等虽在 16.3 已被废弃，但只要应用没开 StrictMode，16/17 会继续静默调用，一个从未用过 StrictMode 的代码库可能囤积成百上千处此类调用。
• 事件委托在 React 17 已改挂载点：事件从document移到根容器。若团队从 16 一路小版本补丁到 18 而从未真正做过 17 迁移，残留的document.addEventListener模式可能再也收不到事件。
• 遗留 Context 在 16/17 全程静默可用：主题、鉴权常靠它实现，直到 React 19 才真正移除。

所以规格反复说“18.3.1 的显式警告是你的朋友”——它把这些历史欠账一次性照出来。本次迁移的目标产物，是一个18.3.1 下零警告的基线代码库，好让后续 React 19 编排（仓库中对应的 react19-commander.agent.md 家族同样存在）能干干净净地开场。

落地清单：一份可直接照做的迁移检查表

Commander 规格末尾给出了完整 checklist，综合全篇可归结为以下可执行顺序（对应仓库 agents/react18-commander.agent.md 原文清单）：

1. 生成审计报告.github/react18-audit.md
2. 精确安装react@18.3.1+react-dom@18.3.1
3. 升级@testing-library/react@14+
4. 解决全部 peer 依赖（npm ls零错误；拦截 Enzyme）
5. componentWillMount→componentDidMount/ constructor
6. componentWillReceiveProps→getDerivedStateFromProps/componentDidUpdate
7. componentWillUpdate→getSnapshotBeforeUpdate/componentDidUpdate
8. 遗留 Context →createContext（含全部 consumer）
9. 字符串 ref →React.createRef()
10. 移除findDOMNode→ 直接 ref
11. ReactDOM.render→createRoot；ReactDOM.hydrate→hydrateRoot
12. 定位并修复自动批处理回归（必要时插入flushSync）
13. 复核事件委托假设（document.addEventListener）
14. 全部测试通过（0 失败）
15. 构建成功
16. React 18.3.1 弃用警告清零

阅读延伸与使用方式

• 主控规格：agents/react18-commander.agent.md —— 五阶段流水线、门禁与验收标准的总纲。
• 五个执行子 Agent：react18-auditor（扫描与报告）、react18-dep-surgeon（锁版与阻断）、react18-class-surgeon（生命周期/API 迁移样板代码）、react18-batching-fixer（批处理分诊）、react18-test-guardian（RTL v14/StrictMode/Enzyme 测试修复）。
• 整组插件形态：plugins/react18-upgrade/README.md —— 6 Agent + 7 Skill 的一键安装与快速开始说明，安装命令为copilot plugin install react18-upgrade@awesome-copilot，随后只需对 Copilot 说 “Start implementing React 18 migration for my class-component codebase” 即可唤起整套流水线。
• 配套 skill：skills/react18-lifecycle-patterns、skills/react18-batching-patterns、skills/react18-legacy-context、skills/react18-string-refs、skills/react18-enzyme-to-rtl、skills/react18-dep-compatibility、skills/react-audit-grep-patterns目录下的文档，分别为各阶段提供更细的迁移模式与参考实现。

本文所述全部版本要求、迁移映射与修复决策均取自上述仓库文件；实际执行时请以你项目package.json的依赖现状为准，并优先在可回滚的分支上按阶段推进。当你的代码库在 18.3.1 下达成“零告警、零失败”时，就等于拿到了通往 React 19 的干净入场券。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot