> For the complete documentation index, see [llms.txt](https://onenesss-organization.gitbook.io/jj-xiaoce/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onenesss-organization.gitbook.io/jj-xiaoce/next.js-kai-fa-zhi-nan/58.-shi-zhan-pian-zui-jia-shi-jian-zong-lan.md).

# 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. 数据库

根据这样一项[数据库统计](https://stateofdb.com/databases)，常用的数据库是 Postgres、MongoDB、MySQL、Redis。

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

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

#### 2. ORM

根据[《实战篇 | React Notes | Prisma》](https://juejin.cn/book/7307859898316881957/section/7324318994751488026) 的介绍，在 Node.js 中，目前使用度和满意度最高的就是 Prisma、Drizzle、Mongoose 了。

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

#### 3. 身份认证

关于身份认证有 3 个主流的技术选型：[Clerk](https://clerk.com/)、 [Supabase](https://supabase.com/)、[Next-Auth](https://next-auth.js.org/getting-started/introduction)

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

#### 4. 状态管理

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

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

#### 5. 国际化

Next.js 项目实现国际化，目前有三个主流的技术选型：[next-i18next](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Fi18next%2Fnext-i18next)、[next-intl](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Famannn%2Fnext-intl)、[next-translate](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Faralroca%2Fnext-translate)

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

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

#### 6. 数据校验

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

#### 7. 环境变量

[T3 Env](https://env.t3.gg/docs/introduction)，使用 Zod 定义环境变量，可对环境变量进行验证并完成自动补全和类型推断。

#### 8. 表单处理

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

#### 9. 代码质量

[Husky](https://typicode.github.io/husky/) + Prettier + ESLint + [Lint-Staged](https://github.com/lint-staged/lint-staged) + [Commitlint](https://commitlint.js.org/) + [Commitizen](https://github.com/commitizen/cz-cli) + VSCode 配置 + [semantic-release](https://github.com/semantic-release/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](https://ui.shadcn.com/) 一起使用，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 ](https://www.npmjs.com/package/@next/bundle-analyzer)用于分析包依赖关系，参考[《实战篇 | 博客 | 性能分析》](https://juejin.cn/book/7307859898316881957/section/7309115349148270642#heading-1)

[Sentry](https://sentry.io/for/nextjs/?utm_source=github\&utm_medium=paid-community\&utm_campaign=general-fy25q1-nextjs\&utm_content=github-banner-nextjsboilerplate-logo)，常见的用于监控错误和性能的解决方案。

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

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

### 推荐集成模板

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

1. [create-t3-app](https://github.com/t3-oss/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](https://github.com/ixartz/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](https://github.com/blitz-js/blitz)（13.4k）

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

### Next-js-Boilerplate 介绍

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

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

使用 Next-js-Boilerplate 模板：

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

如果出现以下这种错误：

![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9d5c7b7a0ce9444ca56daea0379563aa~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=2270\&h=372\&s=117088\&e=png\&b=1e1e1e)

可以改为使用 SSH 地址：

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

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

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

浏览器效果如下：

![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/dd0283882ae842e585ff1bad541d3015~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=2570\&h=1126\&s=237765\&e=png\&b=ffffff)

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

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](https://about.codecov.io/codecov-free-trial/?utm_source=github\&utm_medium=paid-community\&utm_campaign=general-fy25q1-nextjs\&utm_content=github-banner-nextjsboilerplate-logo) + [semantic-release](https://github.com/semantic-release/semantic-release) + VSCode 配置
5. 测试相关： [Vitest](https://vitest.dev/)、[React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)、[Playwright](https://playwright.dev/)、[Percy](https://percy.io/)
6. 可视化相关：[Storybook](https://storybook.js.org/)、[Bundler Analyzer](https://www.npmjs.com/package/@next/bundle-analyzer)
7. 数据监控相关：[Sentry](https://sentry.io/for/nextjs/?utm_source=github\&utm_medium=paid-community\&utm_campaign=general-fy25q1-nextjs\&utm_content=github-banner-nextjsboilerplate-logo) + [Pino.js](https://github.com/pinojs/pino) + [Better Stack](https://betterstack.com/?utm_source=github\&utm_medium=sponsorship\&utm_campaign=next-js-boilerplate) + [Checkly](https://www.checklyhq.com/?utm_source=github\&utm_medium=sponsorship\&utm_campaign=next-js-boilerplate)
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` 文件中：

```bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_pub_key
CLERK_SECRET_KEY=your_clerk_secret_key
```

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

#### 2. 设置远程数据库

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

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

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

```bash
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. 提交消息

```bash
npm run commit
```

#### 5. 运行测试

```bash
npm run test
```

#### 6. 集成和E2E测试

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

#### 7. 部署生产环境

```bash
npm run build
npm run start
```

#### 8. 其他功能

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

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

### 最后

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