前言

根据 Next.js 官网的介绍所知，Next.js 被一些世界上最大的公司使用，使得我们能够利用 React 组件的强大功能创建高质量的 Web 应用程序。

Next.js 是一个用于构建全栈 Web 应用的 React 上层框架，这意味着我们使用 Next.js 不仅可以构建用户界面，而且还可以实现后端接口。在底层，Next.js 帮我们抽象并自动配置 React 所需的工具，例如打包、编译等，这使我们可以更专注于构建应用，而不是花时间进行配置。

虽然 Next.js 帮我们在创建项目的时候增加了一些可选的配置，如 TypeScript、ESLint、Tailwind CSS 等工具类的配置，但是还是缺少企业级相关的配置，如 husky、commitlint、prettier 等，因此迫使我们需要总结一套基于 Next.js 的用于快速构建项目的模板。

Next.js 的特点

开箱即用

Next.js 已经帮我们集成好了各种技术栈，比如：React、webpack、路由、数据获取、SCSS、TypeScript 等，同时也提供了专门的脚手架：create-next-app。

约定式路由

约定式路由也就是所谓的目录结构即路由，Next.js 目前提供两种路由形式，一种是应用路由，在 app 目录结构中自动生成；另一种是页面路由，在 pages 目录结构中自动生成。但是在 Next.js 14 之后，应用路由是创建路由的主要方式，当然你也可以选择性的使用页面路由。

内置 CSS 模块和 Sass 支持

自从 Next.js 9.3 以后就内置了 CSS 模块和 Sass 支持，也是开箱即用的。

全栈开发能力

Next.js 不但支持前端开发，还支持编写后端代码，比如：可开发登录验证、存储数据、获取数据等接口。

多种渲染模式

支持 CSR、 SSR、 SSG、 ISR 等渲染模式，当然也支持混合搭配使用。

利于搜索引擎优化

Next.js 支持使用服务器端渲染，同时它也是一个很棒的静态站点生成器，非常利于 SEO 和首屏渲染。

配置项目模板

创建项目

注意：我们应该保证 Node 的版本为 Node.js 18.17 或更高版本。

首先，在要创建项目的文件夹下的终端命令行直接输入 npx create-next-app@latest，然后根据提示进行选择，按步骤操作就行，值得注意的是，Next.js 现在默认附带 TypeScript、ESLint 和 Tailwind CSS 配置。

然后，等依赖安装完毕，打开项目文件夹，在项目终端命令行输入 npm run dev，项目就运行起来了。

配置 husky

首先，安装 husky，在项目根目录终端命令行输入npm i husky --save-dev，然后输入npx husky init，就会在项目根目录生成一个 .husky 的文件夹，你可以在其中的 pre-commit 文件写一些 git commit 之前的操作，例如执行代码语法的检查 npm run lint。

然后，在 package.json 文件中 husky 就会帮助我们配置上 "prepare": "husky" 脚本。

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "next lint",
  "prepare": "husky" // 此处是执行 npx husky init 后帮我们新增的
}

更多详细的使用技巧可参照 husky 官网的教程。

配置 commitlint

在企业级项目中 git commit 规范是尤为重要的，可参考具体 git commit 的格式规范。

首先，在项目根目录的终端命令行输入如下命令：

npm install --save-dev @commitlint/config-conventional @commitlint/cli

然后，在 package.json 文件中新增如下代码：

"commitlint": {
  "extends": [
    "@commitlint/config-conventional"
  ]
}

最后，在 .husky 文件夹中新建 commit-msg 文件，在里面添加如下内容：

npx --no -- commitlint --edit ${1}

这样在 git commit 之前就会进行 commitlint 操作，检查是否符合规范，不符合规范的 git commit 就会给予提示，重新书写符合规范的 git commit 之后就可以 commit 成功。

配置 prettier

首先，在项目根目录的终端命令行输入 npm install prettier eslint-config-prettier --save-dev，然后在项目根目录新建 .prettierrc.js文件。

然后，你可以在其中增加如下配置，当然你也可以根据自己的喜好自定义配置。

module.exports = {
  printWidth: 120, // 设置每行代码的最大字符数为 120
  useTabs: false, // 是否使用空格而不是制表符（tabs）进行缩进
  tabWidth: 2, // 一个制表符应该占据多少个空格的宽度
  trailingComma: "es5", // 在 ES5 语法中支持的地方添加尾随逗号
  semi: false, // 是否在语句末尾自动添加分号
  singleQuote: true, // 是否使用单引号而不是双引号来包裹字符串
  bracketSpacing: true, // 在对象的大括号之间添加空格。例如，在导入语句中，它会在花括号和导入的成员之间添加空格
  arrowParens: "always", // 在箭头函数的参数周围总是添加括号，即使只有一个参数
  jsxSingleQuote: false, // 是否在 JSX 中使用双引号而不是单引号来包裹字符串
  endOfLine: "lf" // 设置文件的换行符。lf 表示 Unix/Linux 风格的换行符（\n），而 crlf 表示 Windows 风格的换行符（\r\n）。对于 Git 和跨平台协作，通常推荐使用 lf
}

其次，在 .eslintrc.json 文件中增加 prettier。

{
  "extends": ["next/core-web-vitals", "prettier"]
}

最后，在 package.json 文件中新增如下脚本代码：

  "scripts": {
    "format": "prettier --check .",
    "format:fix": "prettier --write --list-different ."
  }

运行 npm run format 就可以进行代码格式的检查，运行 npm run format:fix 就可以对其不规范的代码进行格式化为符合你所配置 prettier 的格式。

因此你可以在 .husky 文件夹中的 pre-commit 文件中增加 npm run format:fix，从而在让 husky 帮助我们在 git commit 之前执行代码格式的检查并修复，新增 git add . 防止格式化代码后再次重复 git add。

环境变量

环境变量的定义

Next.js 内置了对环境变量的支持，我们可以直接在项目根目录创建以下四种文件：

.env：所有环境下都生效的默认设置
.env.development：执行 next dev 时加载并生效，常用于开发环境
.env.production ：执行 next start 时加载并生效，常用于生产环境
.env.local ：始终覆盖上面文件定义的默认值，所有环境均生效，此文件常用于存储敏感信息。

我们可以在上述文件中书写大写单词，其中多个单词使用下划线，比如：DB_HOST=localhost，同时也支持变量，例如 $PORT。添加 NEXT_PUBLIC_ 前缀会额外暴露给浏览器，比如：NEXT_PUBLIC_ANALYTICS_ID=abc。

NAME=localhost
PORT=8888

HOST=http://127.0.0.1

NEXT_PUBLIC_BASE_URL=http://$NAME:$PORT

NEXT_PUBLIC_ANALYTICS_ID=abc

环境变量的获取

.env 文件中定义的环境变量会加载到 process.env 中。

客户端和服务端都可直接通过 process.env.xxx 方式访问使用（不支持解构）。值得注意的是，只有添加 NEXT_PUBLIC_ 前缀的环境变量才能暴露给客户端，而服务端都能访问.env中的环境变量。

export default function Home() {
  // 读取环境变量
  if (typeof window == 'object') {
    console.log('---客户端---', process.env.NEXT_PUBLIC_BASE_URL) // http://localhost:3000
    console.log('---客户端---', process.env.NAME) // undefined
    console.log('---客户端---', process.env.PORT) // undefined
    console.log('---客户端---', process.env.HOST) // undefined
  } else {
    console.log('---服务端---', process.env.NEXT_PUBLIC_BASE_URL) // http://localhost:3000
    console.log('---服务端---', process.env.NAME) // localhost
    console.log('---服务端---', process.env.PORT) // 3000
    console.log('---服务端---', process.env.HOST) // http://127.0.0.1
  }
  return (
    <main className="flex justify-center">nextjs-template</main>
  )
}

由于 .env、 .env.development 和 .env.production 文件定义了默认设置，需提交到源码仓库中，而项目中的.env.local 应添加到 .gitignore 中，因为这类文件常用于存储敏感信息，是需要被忽略的。

应用配置

next.config.js 文件位于项目的根目录，我们可以在该文件对 Next.js 进行自定义配置：

reactStrictMode：是否启用严格模式，辅助开发，避免常见错误，例如：可以检查过期API来逐步升级。
env：配置环境变量，配置完需要重启，此文件会添加到 process.env 中。
basePath：要在域名的子路径下部署 Next.js 应用程序，可以使用 basePath 配置选项。允许为应用程序设置 URl 路径前缀，例如 basePath=/blog，即用 /blog 访问首页，而不是默认 /。
images：可以配置图片 URL 的白名单等信息。

/** @type {import('next').NextConfig} */
const nextConfig = {
   // 是否启用严格模式
  reactStrictMode: true,
  
  // 配置环境变量 注意 配置完需要重启应用
  env: {
    PORT: 9999,
    NEXT_PUBLIC_BASE_URL: "http://localhost:9999",
  },

  // 给网站添加一个路径前缀
  basePath: "/blog"
}

module.exports = nextConfig

值得注意的是，在不同的位置书写环境变量优先级不同，next.config.js 中的 env > .env.local > .env。

更多配置可参考官网中的 next-config-js 配置选项。

总结

既然我们想到了总结项目模板来用于快速构建项目，那么 Vercel 官方肯定帮我们做出了对应的解决方案，没错，Vercel 官方帮我们提供了来自 Vercel 和社区的预构建解决方案来快速启动我们的应用程序开发。其中就包括了很多分类，如 AI、博客、SaaS、CMS 等相关主题的模板，我们也可以针对这些官方或者社区模板作为一个参考，然后在此基础上构建一个属于自己的或者企业的项目模板。

配置一个 Next.js 项目模板，用于项目快速开发

前言