本文介绍一款面向 React 前端开发者的本地开发工具 SpotPatch。它可以在浏览器中直接选择页面元素一键定位到对应的 JSX/TSX 源码收集有限且脱敏的上下文并通过可审阅、可回滚的 AI 工作流辅助修改前端代码。一、前端开发中一个经常被忽略的问题在开发 React、Vite 或 Next.js 页面时我们经常会遇到这样的需求把这个按钮改成蓝色。调整这个卡片的间距。修改页面右上角这个区域。把这个弹窗的标题字体调大。这个元素对应的是哪个 React 组件听起来都是小改动但传统流程往往是这样一套完整链路在浏览器中找到页面元素打开 DevTools 查看 DOM根据 class、文本或组件结构反向搜索项目源码在多个 JSX/TSX 文件中来回确认真正的组件位置手动把上下文复制给 AI 编程工具检查 AI 修改是否影响了其他文件再回到浏览器确认效果。对于中大型前端项目这个过程非常耗时。尤其当项目中出现以下情况时定位难度会进一步上升组件层级较深页面由多个业务组件组合而成className 经过封装或动态生成页面同时存在 Server Component 和 Client Component同一个组件在多个页面复用AI 只拿到一张截图无法确定真实源码位置。SpotPatch 要解决的就是缩短页面反馈到源码修改之间的距离。二、SpotPatch 是什么SpotPatch 是一个本地优先、仅开发期运行的 React 页面反馈工作台。它的核心流程如下浏览器选择元素 ↓ 获取元素对应的源码标记 ↓ 定位 JSX/TSX 文件、行号和列号 ↓ 收集有限且脱敏的上下文 ↓ 生成结构化修改请求 ↓ 复制 Prompt 或运行可审阅的 AI Agent ↓ 查看 Diff、执行检查并决定是否应用需要特别说明SpotPatch 不是截图转代码工具也不是直接修改生产网站的工具。它更关注以下几个问题页面上的这个元素到底对应哪个源码位置如何让 AI 获得准确的 JSX/TSX 上下文而不是猜测如何避免 AI 直接、无审阅地修改当前工作区如何在应用修改前看到完整的 Diff如何保证生产构建中不残留任何开发工具代码三、SpotPatch 的核心能力1. 从页面元素直接定位到 JSX/TSX 源码在开发环境中SpotPatch 会为范围内的 JSX/TSX 元素添加开发期源码标记。用户在页面中选中某个元素后SpotPatch 可以直接返回源码文件路径行号 / 列号元素名称DOM 信息CSS 上下文组件上下文有边界限制的源码片段例如选中一个元素后可能直接得到src/components/HeroSection.tsx:42:8不再需要手动从 DOM 结构反向搜索源码。2. 支持多目标反馈一次任务可以同时选择多个页面元素且每个目标保留独立说明例如目标 1修改导航栏背景色 目标 2调整主按钮圆角 目标 3增大卡片之间的间距每个目标都有独立的源码位置和修改要求避免把多个页面反馈揉进一段模糊的自然语言描述里。3. 不配置 AI 也可以正常使用SpotPatch不强制要求配置 AI。即使没有配置任何 AI Provider也可以正常使用元素选择源码定位上下文查看跳转到 Cursor 或 VS Code 对应位置结构化 Prompt 生成与复制AI 只是一个可选的增强能力不是使用 SpotPatch 的前提条件。4. AI 修改默认需要人工审阅当用户配置了 OpenAI-compatible Provider 后SpotPatch 可以运行一个受限权限的 AI Agent整个工作流包含Provider 能力检测有边界限制的文件读取有边界限制的文件修改项目检查Lint / Build 等Git worktree 隔离Diff 审阅Apply应用修改Revert一键回滚默认情况下AI 的修改不会直接写入当前工作区必须经过 Diff 审阅后手动 Apply。四、在 Vite React 项目中接入1. 安装pnpm add -D spotpatch/vite也可以使用 npmnpm install --save-dev spotpatch/vite2. 配置 Vite 插件在vite.config.ts中添加配置import react from vitejs/plugin-react-swc; import { defineConfig } from vite; import { spotPatch } from spotpatch/vite; export default defineConfig({ plugins: [spotPatch(), react()], });注意spotPatch()需要放在 React 插件之前这样才能确保开发期源码标记在 React 转换之前完成处理。3. 启动开发服务器pnpm dev打开页面后可以通过以下两种方式进入元素选择模式点击页面右下角的Select element按钮使用快捷键ModShiftS。选中页面元素后SpotPatch 会自动显示对应的源码位置和上下文信息。五、配置 AI AgentSpotPatch 的 AI 能力默认关闭。如果需要开启需要配置完整的 Provider 环境变量SPOTPATCH_AI_BASE_URLhttps://your-relay.example/v1 SPOTPATCH_AI_MODELyour-model-name SPOTPATCH_AI_API_KEYyour-api-key可选配置项SPOTPATCH_AI_PROTOCOLchat-completions SPOTPATCH_AI_AUTHENTICATIONbearer当前支持的协议包括chat-completions、responses支持的认证方式包括bearer、x-api-key。⚠️ 安全注意事项API Key 必须只保留在 Node.js 开发进程中绝对不要使用以下前缀否则可能导致敏感信息被打包进浏览器端代码# 错误示范不要这样做 VITE_SPOTPATCH_AI_API_KEY... NEXT_PUBLIC_SPOTPATCH_AI_API_KEY...正确做法是使用不带公开前缀的变量名并将.env.local加入.gitignoreSPOTPATCH_AI_API_KEY...SpotPatch 不会向模型开放任意 Shell 权限也不会让模型直接执行未受限制的系统命令。六、在 Next.js 项目中接入SpotPatch 提供了专门的 Next.js 适配器pnpm add -D spotpatch/next初始化项目pnpm exec spotpatch-next init检查接入结果pnpm exec spotpatch-next check启动开发环境pnpm dev初始化命令会根据项目实际情况自动处理以下内容next.config配置instrumentation-client开发脚本SpotPatch Sidecar 生命周期Loader 配置建议在干净的 Git 工作区中执行初始化并检查生成的文件差异后再提交。七、Next.js 当前支持边界务必了解这里需要特别说明一点spotpatch/next目前是 0.x public preview 版本不代表已经完成全部 Next.js 正式支持矩阵请不要仅凭 peerDependencies 的版本范围推断全部兼容性。目前已验证可用的方向Next.js App RouterServer Component 与 Client ComponentwebpackTurbopack开发期 LoaderSource MapHMR / Fast RefreshRuntime bootstrap源码注册生产构建隔离以下范围仍在持续补齐中Pages RouterApp Router 与 Pages Router 混合项目全量 Next.js 小版本覆盖全量 Node.js 与操作系统组合更复杂的 RSC streaming 场景特殊 basePath复杂 rewritesstandalone 和 static export特殊 webpack / Babel / MDX 配置因此当前更准确的定位是框架当前状态Vite正式公共接入Next.js可安装的开发期公共预览public preview八、生产环境隔离设计SpotPatch只在开发期运行生产构建中不会包含以下任何内容SpotPatch RuntimeJSX/TSX 源码标记本地开发 APISidecar 进程源码注册状态内部会话密钥AI Provider 凭据生产环境依然使用框架原生命令即可pnpm build pnpm start在 Next.js 项目中spotpatch-next只负责开发期生命周期管理不应被当作生产服务器使用。九、项目结构与核心模块SpotPatch 采用多包架构职责划分清晰包名作用spotpatch/viteVite React 开发期接入spotpatch/nextNext.js 开发期适配spotpatch/compilerJSX/TSX 源码标记与 Source Mapspotpatch/dev-server本地开发服务、源码注册、编辑器与 Agent 编排spotpatch/runtime浏览器选择器、上下文采集与工作台spotpatch/react-adapterReact / Fiber 兼容边界spotpatch/agentProvider、受限工具、worktree 与检查流程spotpatch/shared协议、模型与错误码整体数据流可以理解为React / Vite / Next.js ↓ 开发期源码转换 ↓ 源码标记与 Source Map ↓ 浏览器 Runtime ↓ 本地 Dev Server ↓ 源码上下文与编辑器 ↓ 可选 AI Agent十、常见问题 FAQ1. 页面中没有出现选择元素按钮Vite 项目请先确认插件顺序plugins: [spotPatch(), react()]并确认当前运行的是pnpm dev而不是生产预览命令。Next.js 项目需要通过pnpm dev启动经过 SpotPatch 初始化的开发脚本不要绕过初始化脚本直接运行普通的next dev。2. 无法定位到源码怎么办SpotPatch 默认处理src目录下的.jsx和.tsx文件。如果组件来自以下位置可能无法获得精确的源码定位node_modules构建生成目录测试文件未注册的源码目录不在 include 范围内的文件3. AI 显示不可用请确认以下三个变量是否完整存在SPOTPATCH_AI_BASE_URL... SPOTPATCH_AI_MODEL... SPOTPATCH_AI_API_KEY...配置不完整时SpotPatch 会安全地将其视为 AI 不可用状态而不会报错崩溃。4. React 出现 hydration 警告怎么办如果警告信息中出现类似cz-shortcut-listentrue的属性通常说明是浏览器扩展在 React hydration 之前修改了页面 HTML。建议先用一个干净的浏览器 Profile 测试不要直接把此类警告归因于 SpotPatch。十一、项目地址GitHubhttps://github.com/huanglvjing/spotpatchVite 插件https://www.npmjs.com/package/spotpatch/viteNext.js 适配器https://www.npmjs.com/package/spotpatch/next如果在实际项目中遇到问题建议提交 issue 时附上以下信息方便快速定位Node.js 版本React 版本Vite 或 Next.js 版本Router 类型App Router / Pages Routerwebpack 或 Turbopack操作系统最小复现项目终端错误信息浏览器控制台信息十二、总结SpotPatch 解决的是一个非常具体的前端开发问题如何从浏览器中的页面元素快速回到真实的 JSX/TSX 源码并让 AI 在明确上下文和 Diff 审阅的前提下辅助修改代码。它不依赖截图猜测也不要求把整个项目源码上传到第三方服务。目前推荐的使用路径是在 Vite React 项目中安装spotpatch/vite使用页面元素选择功能定位源码不配置 AI 时直接复制结构化 Prompt 交给你习惯的 AI 工具配置 AI 后使用隔离 worktree 和 Diff 审阅机制安全应用修改在 Next.js 项目中可以尝试spotpatch/next的 public preview生产构建始终使用普通框架命令不受 SpotPatch 影响。对于经常进行页面调整、组件定位、设计还原和 AI 辅助开发的前端团队来说SpotPatch 可以把看页面、找源码、写需求、审阅修改连接成一条完整的开发闭环。