z.ai/app-261004

0 Fork 0

Files

T

z.ai b4c7908029

2026-10-08 11:09:37 +08:00

10 KiB

Raw Permalink Blame History

第三方库文档地址汇总

本文件汇总项目中使用到的全部第三方库及其官方文档地址。版本号与 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

附：版本查询与升级

# 查看当前安装版本
pnpm list --depth 0

# 检查过期的依赖
pnpm outdated

# 交互式升级
pnpm update --interactive --latest

如需查询某个包的最新版本与发布时间，可访问 npm 官方页面： https://www.npmjs.com/package/<包名>

10 KiB Raw Permalink Blame History Unescape Escape

第三方库文档地址汇总

一、核心框架

Next.js 相关子文档

二、内容与 MDX 渲染

三、代码高亮

Shiki 相关子文档

四、UI 与样式

Tailwind v4 相关子文档

五、动画

Motion 相关子文档

六、数据库与接口

数据库相关子文档

七、国际化

next-intl 相关子文档

八、字体

字体相关文档

九、开发工具

十、设计规范参考

十一、部署

附：版本查询与升级

10 KiB

Raw Permalink Blame History