AI 摘要：本文系统性地提出了构建 React 组件的十大原则，涵盖服务端渲染（Server Rendering）、水合（Hydration）、多实例、并发渲染（Concurrent Rendering）、组合（Composition）、Portal、View Transition、Activity、数据泄露防护及未来兼容性等现代 React 应用中的关键挑战。作者通过具体代码示例，展示了常见陷阱及其解决方案，强调组件应具备在不可预测环境中稳定运行的能力，而非仅满足“理想路径”下的功能实现。

1. 服务端与水合兼容性
• Server-Proof：避免在组件顶层直接调用浏览器专属 API（如 localStorage），应将相关逻辑移至 useEffect 中，确保服务端渲染（SSR）不崩溃。
• Hydration-Proof：防止水合过程中的视觉闪烁（FOUC），可通过内联 <script> 在 React 水合前同步设置 DOM 状态，确保服务端与客户端初始渲染一致。

2. 多实例与上下文隔离
• Instance-Proof：使用 React 的 useId Hook 为每个组件实例生成唯一 ID，避免多个同类型组件因共享硬编码 ID 而相互干扰。
• Portal-Proof：监听事件时应基于组件所在 DOM 的 ownerDocument.defaultView 获取正确 window 对象，确保在 iframe、弹窗或 createPortal 场景下仍能正常工作。

3. 并发与异步渲染适配
• Concurrent-Proof：在 Server Component 中使用 React.cache 包装数据获取逻辑，避免同一请求内多次重复调用相同异步操作。
• Transition-Proof：配合 React 19 的 <ViewTransition> 实现平滑 UI 切换时，状态更新需通过 startTransition 触发，以启用过渡动画。

4. 组合性与副作用管理
• Composition-Proof：优先使用 Context 而非 React.cloneElement 向子组件传递数据，以兼容 Server Component、lazy 加载和异步 children 等现代 React 特性。
• Activity-Proof：对于通过 <style> 注入全局 CSS 变量的组件，在被 <Activity> 隐藏时应通过 useLayoutEffect 动态设置 media="not all" 来禁用样式，防止副作用残留。

5. 安全与未来兼容性
• Leak-Proof：利用 experimental_taintUniqueValue 或 experimental_taintObjectReference 标记敏感数据（如 token），防止其意外序列化并泄露至客户端。
• Future-Proof：当组件行为依赖值的持久性时（如随机色生成），应使用 useState 而非 useMemo，因为后者仅为性能提示，React 可能在 HMR 或未来优化中丢弃缓存。

shud.in

Building Bulletproof React Components - Shu Ding

The real test isn’t whether your component works on your current page. It’s whether it works when someone else uses it.