233 lines
10 KiB
Markdown
233 lines
10 KiB
Markdown
# 第三方库文档地址汇总
|
||
|
||
> 本文件汇总项目中使用到的全部第三方库及其官方文档地址。
|
||
> 版本号与 `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/<包名>`
|