手绘 UI 组件库开源维护手记处理首批 Issue 与 PR昨天「Tide UItide-ui/react」开源发布后的 24 小时内GitHub 仓库收到了来自全球各地开发者的18 个 Issue 和 4 个 Pull Request。作为一个原本只是为了自己写独立产品而抽象出来的内部组件库当它第一次暴露在形形色色、五花八门的用户真实生产环境Next.js App Router、Nuxt 3、Remix、甚至老旧的 Webpack 4 工程中时各种在本地开发时从未预料到的兼容性边界问题立刻浮出了水面。今天我把处理这首批 Issue 和 PR 的实战复盘与开源项目的标准化维护 SOP整理出来。-------------------------------------------------------------------- | Tide UI 首批高频 Issue 分类与修复架构 | ------------------------------------------------------------------ | 核心问题分类 | 开发者反馈场景 | 根因剖析与标准解法 | ------------------------------------------------------------------ | 1. Next.js SSR 报错 | use client 缺失 | 在 tsup 打包入口顶部 | | | 在服务端组件中导入 | 自动注入 banner: use client| | 2. CSS Modules 冲突 | 宿主全局 reset 样式 | 提升手绘 CSS 权重为 | | | 覆盖了手绘边框圆角 | layer tide-components | | 3. Svelte/Vue 适配 | 社区提出跨框架诉求 | 抽离纯 Web Components 核心| ------------------------------------------------------------------1. 致命修复一Next.js App Router 的 use client 指令注入有三位开发者提 Issue 反馈在 Next.js 14/15 的app/page.tsx中直接导入HandDrawnCard时抛出异常React Context is not available in Server Components。虽然我们的组件内部使用了 React Hook但经过 tsup 打包成单个 JS 文件后文件顶部丢失了use client声明。在tsup.config.ts中加入自动 Banner 注入import { defineConfig } from tsup; export default defineConfig({ entry: [src/index.ts], format: [esm, cjs], dts: true, // 核心强制在产物首行注入客户端标记 banner: { js: use client;, }, });2. 致命修复二利用 CSS layer 彻底解决样式覆盖问题很多宿主项目使用了Tailwind Preflight或Normalize.css其全局重置规则把.hand-drawn-border的复杂圆角给覆盖掉了。我们将 Tide UI 的所有核心样式包裹在现代标准的layer tide-ui级联层中layer tide-ui { .tide-card { border: var(--tide-border-solid); border-radius: 255px 15px 225px 15px / 15px 225px 15px 255px; } }使用layer后宿主应用可以随意通过外部 CSS 类名覆盖组件样式同时组件默认样式永远不会被第三方全局 reset 粗暴破坏。3. 开源维护者的心力管理面对社区的各种新需求“能不能加个 Material Design 主题”、“能不能做三维旋转”学会温和而坚定地说“No”是一名合格开源作者最重要的必修课。守住 Tide UI“温润治愈手作风”的纯粹定位不盲目追求功能的泛滥项目才能走得长远。