2026-10-08 11:09:37 +08:00
1 parent c1541b80df
commit b4c7908029
@@ -0,0 +1,232 @@
+# 第三方库文档地址汇总
+
+> 本文件汇总项目中使用到的全部第三方库及其官方文档地址。
+> 版本号与 `package.json` 保持一致，便于查阅对应版本的 API。
+
+---
+
+## 一、核心框架
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| Next.js | 16.3.8 | React 全栈框架（App Router、SSG、字体优化、SEO 元数据） | https://nextjs.org/docs |
+| React | 19.2.8 | UI 库（Server Components / Client Components） | https://react.dev |
+| React DOM | 19.2.8 | React 的 DOM 渲染器 | https://react.dev/reference/react-dom |
+| TypeScript | 5.x | 类型系统 | https://www.typescriptlang.org/docs/ |
+
+### Next.js 相关子文档
+
+| 主题 | 文档地址 |
+| --- | --- |
+| App Router 路由约定 | https://nextjs.org/docs/app/building-your-application/routing |
+| Server / Client Components | https://nextjs.org/docs/app/building-your-application/rendering/server-components |
+| `next/font` 字体优化（自托管） | https://nextjs.org/docs/app/api-reference/components/font |
+| `generateMetadata` 与 SEO | https://nextjs.org/docs/app/api-reference/functions/generate-metadata |
+| `sitemap.xml` 生成 | https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap |
+| `robots.txt` 生成 | https://nextjs.org/docs/app/api-reference/file-conventions/metadata/robots |
+| `not-found` 404 页面 | https://nextjs.org/docs/app/api-reference/file-conventions/not-found |
+| `loading` 加载态 | https://nextjs.org/docs/app/api-reference/file-conventions/loading |
+| `error` 错误边界 | https://nextjs.org/docs/app/api-reference/file-conventions/error |
+| `next/image` 图片优化 | https://nextjs.org/docs/app/api-reference/components/image |
+| `middleware` → `proxy` 迁移说明 | https://nextjs.org/docs/messages/middleware-to-proxy |
+
+---
+
+## 二、内容与 MDX 渲染
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| next-mdx-remote | 6.0.0 | 在 Server Component 中编译并渲染 MDX | https://github.com/hashicorp/next-mdx-remote |
+| gray-matter | 4.0.3 | 解析 Markdown 的 YAML frontmatter | https://github.com/jonschlinkert/gray-matter |
+| remark-gfm | 4.0.1 | 支持 GitHub 风格 Markdown（表格、任务列表、删除线） | https://github.com/remarkjs/remark-gfm |
+| rehype-slug | 6.0.0 | 为标题自动生成锚点 id（目录跳转依赖） | https://github.com/rehypejs/rehype-slug |
+| rehype-autolink-headings | 7.1.0 | 为标题生成可点击的锚点链接 | https://github.com/rehypejs/rehype-autolink-headings |
+
+---
+
+## 三、代码高亮
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| Shiki | 4.5.0 | 基于 TextMate 语法的代码高亮引擎（构建期高亮，运行时零 JS） | https://shiki.style |
+| rehype-pretty-code | 0.14.5 | 将 Shiki 接入 rehype 管线，提供行号、高亮行等能力 | https://rehype-pretty.pages.dev |
+
+### Shiki 相关子文档
+
+| 主题 | 文档地址 |
+| --- | --- |
+| 主题列表与预览 | https://shiki.style/themes |
+| 支持的语言 | https://shiki.style/languages |
+| 双主题（明暗）配置 | https://shiki.style/guide/dual-themes |
+
+> 本项目使用 `github-dark-default` 主题，在 `{colors.surface-code}`（`#1c1c1e`）深色底上对比度良好。
+
+---
+
+## 四、UI 与样式
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| Tailwind CSS | 4.x | 原子化 CSS 框架（`@theme` 声明设计令牌） | https://tailwindcss.com/docs |
+| @tailwindcss/postcss | 4.x | Tailwind v4 的 PostCSS 插件 | https://tailwindcss.com/docs/installation/framework-guides/nextjs |
+| class-variance-authority | 0.7.1 | 管理组件样式变体（variant / size） | https://cva.style/docs |
+| clsx | 2.1.1 | 条件拼接 className | https://github.com/lukeed/clsx |
+| tailwind-merge | 3.7.0 | 消解冲突的 Tailwind 类名 | https://github.com/dcastil/tailwind-merge |
+| lucide-react | 1.51.0 | 图标库 | https://lucide.dev/icons |
+
+### Tailwind v4 相关子文档
+
+| 主题 | 文档地址 |
+| --- | --- |
+| `@theme` 定义设计令牌 | https://tailwindcss.com/docs/theme |
+| 自定义工具类 `@utility` | https://tailwindcss.com/docs/adding-custom-styles#customizing-your-theme |
+| 响应式断点 | https://tailwindcss.com/docs/responsive-design |
+| 深色模式（本项目未启用） | https://tailwindcss.com/docs/dark-mode |
+
+> **lucide-react 注意事项**：v1.x 起已移除品牌图标（`Github`、`Twitter` 等）。
+> 如需品牌图标，请使用 https://simpleicons.org 或 https://github.com/lobehub/lobe-icons 。
+
+---
+
+## 五、动画
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| Motion | 14.0.0 | 动画库（Framer Motion 的继任者），用于入场动画与阅读进度条 | https://motion.dev/docs |
+
+### Motion 相关子文档
+
+| 主题 | 文档地址 |
+| --- | --- |
+| React 快速上手 | https://motion.dev/docs/react-quick-start |
+| `useScroll` 滚动关联动画 | https://motion.dev/docs/react-use-scroll |
+| `useSpring` 弹簧平滑 | https://motion.dev/docs/react-use-spring |
+| `useReducedMotion` 无障碍 | https://motion.dev/docs/react-use-reduced-motion |
+
+> **重要实现说明**：本项目**刻意未使用** `whileInView`。
+> 它会在服务端输出 `opacity: 0`，只有 JS 执行且元素滚入视口后才显示；
+> 一旦 JS 加载失败，文章列表将永久不可见，且不利于 SEO。
+> 因此改为「渐进增强」：服务端输出可见 HTML，客户端仅在元素位于视口下方时叠加一次过渡动画。
+> 参见 `components/motion/reveal.tsx` 与 `components/motion/motion-item.tsx`。
+
+---
+
+## 六、数据库与接口
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| node-postgres (`pg`) | 8.23.1 | PostgreSQL 驱动（TCP 连接池） | https://node-postgres.com |
+| Drizzle ORM | 0.45.3 | 类型安全的 SQL 查询构建器 | https://orm.drizzle.team/docs/overview |
+| Drizzle Kit | 0.31.11 | 迁移生成与执行、Studio | https://orm.drizzle.team/docs/kit-overview |
+| Zod | 4.6.5 | 请求参数与请求体的运行时校验 | https://zod.dev |
+
+### 数据库相关子文档
+
+| 主题 | 文档地址 |
+| --- | --- |
+| node-postgres 连接池 | https://node-postgres.com/apis/pool |
+| node-postgres SSL 配置 | https://node-postgres.com/features/ssl |
+| Drizzle + node-postgres 接入 | https://orm.drizzle.team/docs/get-started-postgresql |
+| Drizzle Schema 定义（pgTable） | https://orm.drizzle.team/docs/sql-schema-declaration |
+| Drizzle 索引定义 | https://orm.drizzle.team/docs/indexes-constraints |
+| Drizzle 查询（select/where/orderBy） | https://orm.drizzle.team/docs/data-querying |
+| Drizzle 迁移（generate / migrate） | https://orm.drizzle.team/docs/migrations |
+| Drizzle Studio | https://orm.drizzle.team/docs/studio |
+| PostgreSQL 错误码对照 | https://www.postgresql.org/docs/current/errcodes-appendix.html |
+| Zod 对象 schema 与 refine | https://zod.dev/api |
+| PostgreSQL 数组类型与 GIN 索引 | https://www.postgresql.org/docs/current/indexes-types.html |
+
+> **驱动选择说明**：项目**不使用** `@neondatabase/serverless` 的 `neon-http` 驱动。
+> 它走 Neon 的 HTTP 代理端点而非 PostgreSQL TCP 协议，无法连接本地/自建 Postgres。
+> 改用 `pg` 后，本地与 Neon / Supabase / Railway 等标准 Postgres 都能直连，
+> 部署时只需更换连接串。
+>
+> 若确实需要使用 Neon 的 HTTP 驱动，参见：
+> https://orm.drizzle.team/docs/connect-neon
+
+---
+
+## 七、国际化
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| next-intl | 4.14.9 | App Router 国际化（路由前缀、消息、服务端翻译） | https://next-intl.dev/docs |
+
+### next-intl 相关子文档
+
+| 主题 | 文档地址 |
+| --- | --- |
+| 开始使用（App Router） | https://next-intl.dev/docs/getting-started/app-router |
+| 路由与 `defineRouting` | https://next-intl.dev/docs/routing |
+| 服务端 `getTranslations` | https://next-intl.dev/docs/environments/server-client-components |
+| 导航封装 `createNavigation` | https://next-intl.dev/docs/routing/navigation |
+| 静态渲染 `setRequestLocale` | https://next-intl.dev/docs/routing/setup#static-rendering |
+
+---
+
+## 八、字体
+
+字体通过 `next/font/google` 在**构建期下载并自托管**，运行时不会请求 Google 服务器。
+
+| 字体 | 用途 | 授权 | 来源 |
+| --- | --- | --- | --- |
+| Inter | 英文 / UI 正文 | SIL Open Font License 1.1 | https://fonts.google.com/specimen/Inter |
+| Noto Sans SC | 中文 | SIL Open Font License 1.1 | https://fonts.google.com/noto/specimen/Noto+Sans+SC |
+| IBM Plex Mono | 代码 | SIL Open Font License 1.1 | https://fonts.google.com/specimen/IBM+Plex+Mono |
+
+### 字体相关文档
+
+| 主题 | 文档地址 |
+| --- | --- |
+| Inter 官方站点 | https://rsms.me/inter/ |
+| Noto 字体项目 | https://notofonts.github.io |
+| IBM Plex 官方站点 | https://www.ibm.com/plex/ |
+| `next/font` 自托管机制 | https://nextjs.org/docs/app/api-reference/components/font#self-hosting-fonts |
+
+---
+
+## 九、开发工具
+
+| 库 | 版本 | 用途 | 文档地址 |
+| --- | --- | --- | --- |
+| ESLint | 9.x | 代码检查 | https://eslint.org/docs/latest/ |
+| eslint-config-next | 16.3.8 | Next.js 官方 ESLint 规则 | https://nextjs.org/docs/app/api-reference/config/eslint |
+| PostCSS | 4.x | CSS 处理管线 | https://postcss.org |
+| pnpm | 12.3.4 | 包管理器 | https://pnpm.io/motivation |
+
+---
+
+## 十、设计规范参考
+
+| 资源 | 说明 | 地址 |
+| --- | --- | --- |
+| DESIGN.md | 本项目设计令牌来源（Mintlify 设计系统分析） | 见仓库根目录 `DESIGN.md` |
+| design.md 校验工具 | 检查设计令牌引用与对比度 | https://getdesign.md |
+| Mintlify 设计系统 | 上游设计语言参考 | https://getdesign.md/mintlify/design-md |
+
+---
+
+## 十一、部署
+
+| 平台 | 用途 | 文档地址 |
+| --- | --- | --- |
+| Vercel | 推荐的部署平台（Node.js 运行时、自动 HTTPS、自定义域名） | https://vercel.com/docs |
+| Next.js 部署指南 | 自托管与各平台部署说明 | https://nextjs.org/docs/app/building-your-application/deploying |
+
+---
+
+## 附：版本查询与升级
+
+```bash
+# 查看当前安装版本
+pnpm list --depth 0
+
+# 检查过期的依赖
+pnpm outdated
+
+# 交互式升级
+pnpm update --interactive --latest
+```
+
+> 如需查询某个包的最新版本与发布时间，可访问 npm 官方页面：
+> `https://www.npmjs.com/package/<包名>`