58-实战篇 最佳实践总览

前言

在之前的项目中，我们都是使用 npx create-next-app@latest初始化项目，它是 Next.js 的官方脚手架，提供了开发 Next.js 项目最基础的配置。

然而在实际的开发中，Next.js 通常会搭配多种技术选型一起使用，比如 Tailwind CSS、TypeScript、Prisma、Drizzle、NextAuth.js、tRPC、ESLint、Prettier、Husky、Lint-Staged、Commitlint 等等。

它们解决的问题各不相同，本篇我们就来盘点下 Next.js 项目常搭配的主流技术选型。

推荐技术选型

1. 数据库

根据这样一项数据库统计，常用的数据库是 Postgres、MongoDB、MySQL、Redis。

其中 Redis 常被用作缓存层，MongoDB 是非关系型数据库，MySQL 是老牌的关系型数据库，Postgres 则比较轻量。

其实用哪个数据库都可以，云数据库也很不错，最主要看开发者的熟悉程度和喜好。此外，数据库往往会搭配 ORM 一起使用，即便切换数据库，切换成本也比较低。

2. ORM

根据《实战篇 | React Notes | Prisma》 的介绍，在 Node.js 中，目前使用度和满意度最高的就是 Prisma、Drizzle、Mongoose 了。

在实际的项目开发中，理论上应该选择使用度更高、版本相对稳定的库。简而言之，初学者推荐用 Prisma。如果你用 MongoDB，可以选择 Mongoose。新项目尝鲜可以使用 Drizzle。

3. 身份认证

关于身份认证有 3 个主流的技术选型：Clerk、 Supabase、Next-Auth

其中 Clerk 和 Supabase 是平台，接入成本低，但免费版有限制。Clerk 更专注于身份验证和用户管理，对应功能更加丰富。Supabase 实现的功能更多，身份验证只是其中之一。Next-auth 不是平台，是一个开源库，可以帮助我们快速实现登录注册等功能。

4. 状态管理

Next.js 的状态管理参考 React 的状态管理库，其实可用的库特别多。但优先推荐 Zustand。

Zustand 是 2021 年 Star 增长最快的 React 状态管理库，API 设计优雅，业务侵入小，学习成本低，十分推荐。

5. 国际化

Next.js 项目实现国际化，目前有三个主流的技术选型：next-i18next、next-intl、next-translate

react-i18next 配置繁琐，但更为灵活自由。next-intl 配置简单，相对限制更多，部分配置无法自定义。

也有一些搭配它们使用的做本地化的平台，比如 Phrase Localization Platform、Lokalise、Crowdin。你可以把它简单的理解为管理翻译文件的平台，可以上传、翻译、下载文件。

6. 数据校验

Zod 是一个 TypeScript 优先的模式声明和验证库。Next.js 官方文档示例中用到的正是 Zod。

7. 环境变量

T3 Env，使用 Zod 定义环境变量，可对环境变量进行验证并完成自动补全和类型推断。

8. 表单处理

React Hook Form （40.1k Star）是一个老牌的用于 React 应用程序的表单验证和状态管理库。它提供了一组钩子，可以轻松地创建和管理表单，而无需编写大量样板代码。

9. 代码质量

Husky + Prettier + ESLint + Lint-Staged + Commitlint + Commitizen + VSCode 配置 + semantic-release，涉及到的工具有点多，但也算是常见的搭配了。

Husky 用于添加 Git Hooks，ESLint 用于代码校验，Prettier 用于代码美化、Lint-staged 用于在 git 暂存文件上指定 Lint 检查。

Commitlint 用于校验 Git Commit Messge，Commitizen 用于优化提交信息。Commitlint 与 Commitizen 的区别在于 Commitlint 校验提交信息，Commitizen 辅助填写提交信息；在 Git 提交工作流程中，Commitlint 作用于 commit-msg 阶段，Commitizen 作用于 pre-commit。

semantic-release 做自动化 changelog 生成 自动化包的发布工作流程，包括：确定下一个版本号，生成发行说明，以及发布包。

10. CSS

Tailwind CSS 是一个用于构建 Web 项目的 CSS 框架，它提供了一系列预定义的原子CSS类，可以帮助开发人员快速构建 Web 界面，并且可以通过自定义主题和扩展来满足不同的需求。

常搭配组件库 shadcn/ui 一起使用，shadcn/ui 是 2023 年 GitHub Stars 增长最快的 JavaScript 开源项目。

11. 测试相关

Vitest 是一款JavaScript 的单元测试框架。React Testing Library 是一款用于 React 组件的 DOM Testing Library

Playwright 是一个由 Microsoft 开发的用于浏览器测试和网页抓取的开源自动化库。

Codecov 是一个用于代码覆盖率分析的工具，它可以帮助开发人员了解他们的代码被测试的程度。Codecov 支持多种编程语言，并提供多种功能，例如可视化覆盖率报告、代码审查集成和与其他工具的集成

12. UI 开发

Storybook 是一个用于开发 UI 组件的开源工具，它允许您创建可交互的组件并将其独立于应用程序进行开发和测试。Storybook 支持多种框架，包括 React、Vue、Angular 等。

简单来说，Storybook 用于可视化查看 UI 组件，组件根据不同的 props 传入形成不同的 “ story”，共同组成了一个 “Storybook”。可用于测试组件、添加组件文档。

13. 数据分析

Bundler Analyzer 用于分析包依赖关系，参考《实战篇 | 博客 | 性能分析》

Sentry，常见的用于监控错误和性能的解决方案。

Pino 是一个非常快速且简洁的 Node.js 日志库，其设计宗旨在于提供最小的开销以及高性能的日志记录功能。

Better Stack是一个日志管理与分析协作平台，通过将监控、日志记录、事件管理和状态页面整合到一个平台中，为开发人员提供实时协作服务。

推荐集成模板

如果将这些技术选型从头配置，属实有些慢，业界也有很多现成的模板、CLI、脚手架等可以直接使用。这其中最常用的有：

1. create-t3-app（23.7k）

create-t3-app 是一个交互式的 Cli 用于启动一个全栈、类型安全的 Next.js 应用程序。它专注于简单性、模块化和全栈类型安全。它的技术栈包括 Next.js、tRPC、Tailwind CSS、TypeScript、Prisma、Drizzle、NextAuth.js

2. Next-js-Boilerplate（7.6k）

Next-js-Boilerplate 是一个 Next.js 项目模板。它的技术栈包括：Next.js + TypeScript + ESLint + Prettier + Husky + Lint-Staged + Jest + Testing Library + Cypress + Storybook + Commitlint + VSCode + Netlify + PostCSS + Tailwind CSS

3. Blitz（13.4k）

Blitz 致力于添补 Next.js 缺失的全栈工具，比如类型安全的内容层（RPC）、Authentication、各种预配置（eslint、prettier、husky git hooks 等）、丰富的脚手架用于创建各种技术选型方案。

Next-js-Boilerplate 介绍

这个模板涉及的技术栈众多且基本都是主流技术选型，熟悉这个模板，可以帮助大家快速建立起自己的 Next.js 最佳实践模板。

不过这个模板的技术选型也太多了，如果你不喜欢，后面我们还会专门介绍 create-t3-app

使用 Next-js-Boilerplate 模板：

git clone --depth=1 https://github.com/ixartz/Next-js-Boilerplate.git my-project-name

如果出现以下这种错误：

可以改为使用 SSH 地址：

git clone --depth=1 git@github.com:ixartz/Next-js-Boilerplate.git my-project-name

项目运行方式同正常的 Next.js 项目：

# 进入项目目录
cd my-project-name
# 安装
npm install
# 开启开发模式
npm run dev

浏览器效果如下：

简单总结一下这个模板的功能：

1. App Router + TypeScript + Tailwind CSS
2. 自带鉴权（Clerk）和国际化实现（next-intl 和 Crowdin）
3. 配套技术选型：React Hook Form（表单处理） + Zod（数据校验）
4. 提升代码和 Git 提交质量相关：Husky +Prettier + ESLint + Lint-Staged + Commitlint + Commitizen + Codecov + semantic-release + VSCode 配置
5. 测试相关： Vitest、React Testing Library、Playwright、Percy
6. 可视化相关：Storybook、Bundler Analyzer
7. 数据监控相关：Sentry + Pino.js + Better Stack + Checkly
8. SEO 相关：metadata, JSON-LD、Open Graph tags、Sitemap.xml、robots.txt
9. 数据库相关： Drizzle + Turso

总的来说，使用这个模板的好处在于：

1. 只是作为项目的初始化代码，拥有高度自由根据自己的需要调整配置，且容易自定义
2. 最小化代码模板、SEO 友好、可用于生产环境

如何使用

最后我们介绍一下如何使用这个模板。因为这个项目涉及的技术栈和平台众多，很多都需要登录到对应的平台上，获取特殊的 key 或者 token 等。所以如果真的要使用这些技术栈的话，还要做一些配置：

1. 设置身份验证

在 Clerk.com 创建一个 Clerk 帐户，并在 Clerk Dashboard 中创建新应用程序。然后，将 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY 复制到 .env.local 文件中：

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_pub_key
CLERK_SECRET_KEY=your_clerk_secret_key

现在就拥有了一个功能齐全的身份验证系统：注册、登录、注销、忘记密码、重置密码、更新个人资料、更新密码、更新电子邮件、删除帐户等等。

2. 设置远程数据库

首先，需要在 Turso.tech 创建一个 Turso 帐户并安装 Turso CLI：

brew install tursodatabase/tap/turso
turso auth signup # Sign up to Turso

然后，创建一个新数据库：

turso db create nextjs-boilerplate

再然后，使用 Turso 提供的数据库 URL 更新 .env 文件中的 DATABASE_URL：

turso db show nextjs-boilerplate --url

# .env
# DATABASE_URL=libsql://[RANDOM-CHARS]-[DB-NAME]-[ORG-NAME].turso.io

最后，还需要使用 Turso 提供的身份验证令牌在 .env.local 中创建一个新的环境变量 DATABASE_AUTH_TOKEN：

turso db tokens create nextjs-boilerplate

# .env.local
# DATABASE_AUTH_TOKEN=[your-auth-token]

3. 修改自定义配置

项目搜索 FIXME可以看到一些需要自定义配置的地方。这是一些需要自定义的最重要的文件：

• public/apple-touch-icon.png、public/favicon.ico、public/favicon-16x16.png 、public/favicon-32x32.png: 网站图标，可以从 https://favicon.io/favicon-converter/ 生成
• src/utils/AppConfig.ts: 配置文件
• src/templates/BaseTemplate.tsx: 默认主题
• next.config.mjs: Next.js 配置
• .env: 环境变量

4. 提交消息

npm run commit

5. 运行测试

npm run test

6. 集成和E2E测试

npx playwright install # Only for the first time in a new environment
npm run test:e2e

7. 部署生产环境

npm run build
npm run start

8. 其他功能

• 如果要设置翻译功能 (i18n)，需要登录 Crowdin.com 创建帐户并进行配置
• 如果要用到 Sentry，需要登录 Sentry 创建账号并进行配置
• 如果要用到代码覆盖率报告，需要创建 Codecov 帐户并进行设置
• 如果要查看日志，需要 Better Stack 账户并进行配置

具体的配置方案可以在官方文档中查看：https://github.com/ixartz/Next-js-Boilerplate

最后

是不是感觉有些懵逼？怎么突然多了这么多没听说过的平台和工具？没有关系，我们会在后续的篇章中详细介绍。本篇只是作为总览，让大家有个大致的印象和参考。