准备工作

2025年8月12日 · 2064 字

管理代码仓库

无论你使用开源模板还是付费模板，亦或者是你从零开始开始创建一个 Next.js 的项目。你都需要管理代码仓库。

新建一个 Next.js 项目

如果打算新创建一个 Next.js 项目，那么你可以使用 Next.js 官方文档进行创建。

npx create-next-app@latest

接着你 push 代码到你的私有仓库即可。

如果你是使用开源模板，或者像是 NextDevKit 这样的付费模板，那么你可以使用以下两种方式来管理代码仓库：

方式一：fork 代码仓库到你的 GitHub 账号

点击代码仓库 fork，你可以在你的 GitHub 账号下看到一个 fork 后的私有代码仓库。

你可以将这个私有代码仓库 clone 到你的本地，然后 git commit 和 git push 等。这种方式的好处是可以在 GitHub 中 sync 源仓库的代码，并且可以随时查看代码的变更历史，也可以发起 PR 等。

第二种是直接 clone 代码仓库到你的本地。然后在你的组织或者个人仓库新建一个私有仓库，将 clone 的代码 push 到你的私有仓库。

clone-code

clone 代码

在选择 clone 代码的时候，常用的有两种方式，一种是 HTTPS 方式，一种是 SSH 方式。

HTTPS 方式

使用 HTTPS 方式 clone 代码，更推荐使用 GitHub 官方的 cli 工具 gh 进行 clone。参考 gh 官方安装文档进行安装。

如果你是第一次使用 gh 工具，需要先进行登录。

gh auth login

如果你已经使用过 gh 工具，并且已经登录过，还无法 clone 代码，那么需要检查你的 gh 登录账号是否正确。

gh auth status

如果登录账号不正确，那么需要重新登录。

接着你可以使用传统的 git clone 命令进行 clone 代码。注意替换你需要 clone 的代码仓库的 URL。

git clone https://github.com/xxx.git

SSH 方式

第二种方式是使用 SSH 方式 clone 代码，首先需要生成 SSH 密钥。你可以修改 ed25519 为其它名字。

ssh-keygen -t ed25519 -C "your_email@example.com"

接着将生成的公钥添加到 GitHub 中。

cat ~/.ssh/id_ed25519.pub

在 GitHub 的右上角，点击你的头像，然后点击 Settings。在侧边栏的 "Access" 部分，点击 SSH and GPG keys。点击 New SSH key or Add SSH key。将生成的公钥粘贴到 Key 文本框中。点击 Add SSH key 按钮。

更多细节请参考 GitHub 官方文档。

接着你就可以使用 SSH 方式 clone 代码了。

git clone git@github.com:xxx.git

以上两种方式对于私有仓库来讲，都是最比较常用的 clone 代码的方式。具体选择看个人习惯。

安装 IDE 插件

IDE 的选择

在选择 IDE 的时候，你可以按照你的习惯来，由于作者是主要使用 Cursor 开发代码，所以本教程更推荐 VSCode 及其衍生品例如 Cursor 等作为 IDE。

以下推荐的 IDE 插件，都是基于 VSCode 的。如果你使用 IDEA 或者 WebStorm 等 IDE，请根据实际情况进行调整。

在 clone 代码后，你需要安装一些 IDE 插件，以便于你进行代码的开发和 lint 等。

必装并不意味着你没有这个插件无法开发，而是有了这个插件可以极大程度提高你的开发效率。

必装插件

Biome(biomejs.biome): 一个现代的 JavaScript 和 TypeScript 代码检查器。
i18n-ally(Lokalise.i18n-ally): 一个 i18n 的辅助工具。

上面两个插件都默认配置在代码的 .vscode 目录的 extensions.json 文件中，所以你使用 VSCode 打开代码后，会自动弹出推荐安装这两个插件。只需要你点击安装即可。如果没有弹出或者没看到，你只需要手动搜索插件名称，然后点击安装即可。

node.js 和 pnpm

我们默认使用 Nodejs v20 以上的版本作为开发环境，你也可以安装 Nodejs 的最新稳定版本。

你也可以使用 nvm 或者其他版本管理工具来管理 Nodejs 的版本。参考 nvm 官方安装文档进行安装。

brew install nvm

nvm install --lts
nvm use --lts

使用 pnpm 作为包管理工具，你可以使用以下命令安装 pnpm。

npm install -g pnpm@10.10.0

接着安装所有依赖。

pnpm install

如果你 pnpm install 失败，请检查你的网络或者操作系统版本是否兼容。

Lint 和 Format

依赖安装后，就要准备本地开发环境了。在代码开发过程中，Lint 和 Format 是两个非常重要的环节。

你可以按照 NextDevKit 的默认配置，也可以按照你自己的需求进行配置。

Linting（代码检查）：

分析代码中的潜在错误、bug 和代码质量问题。检查代码风格一致性、最佳实践。例如：未使用的变量、缺少分号、使用 == 而不是 ===。

Formatting（代码格式化）：

统一代码的外观和布局，处理缩进、换行、空格、引号等。不改变代码逻辑，只改变显示格式。

常用的 Lint 和 Format 工具有 Biome、ESLint、Prettier 等。NextDevKit 默认集成了 Biome，并且配置了默认的 Lint 和 Format 规则。

现在的 Next.js 项目，我更推荐使用 Biome，原因是：

配置简单，维护成本低。
性能更好。
一个工具解决两个问题。
与现代开发工作流集成良好。

对于已有项目，如果迁移成本不高，也建议逐步迁移到 Biome。

下面是他们的区别，仅供参考，如果你不熟悉，可以直接忽略，跳转到如何使用，使用模板默认配置即可：

Biome vs ESLint + Prettier

ESLint + Prettier（传统方案）

// .eslintrc.json
{
  "extends": ["eslint:recommended"],
  "rules": {
    "no-unused-vars": "error",
    "prefer-const": "warn"
  }
}

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2
}

优点：

生态成熟，插件丰富
社区支持好，文档完善
高度可定制

缺点：

需要配置两个工具
可能存在规则冲突
性能相对较慢

Biome（现代一体化方案）

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noDebugger": "error"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  }
}

优点：

一个工具同时处理 linting 和 formatting
性能更快（Rust 编写）
配置简单，开箱即用
没有工具间的冲突问题

缺点：

相对较新，生态还在发展
自定义规则较少
某些特殊需求可能不支持

Biome 常用配置和使用方法

在 package.json 中，使用默认已经添加的脚本命令，就可以进行 Lint 和 Format 了。

{
  "scripts": {
    "lint": "biome check --write .",
    "lint:fix": "biome check --fix --unsafe .",
    "format": "biome format --write .",
  }
}

使用以下命令进行 Lint 和 Format。

pnpm lint
pnpm lint:fix
pnpm format

命令对比总结

命令	Linting	Formatting	安全修复	不安全修复	用途
`pnpm lint`	✅	✅	✅	❌	日常开发检查
`pnpm lint:fix`	✅	✅	✅	✅	深度清理代码
`pnpm format`	❌	✅	❌	❌	仅格式化

Git hooks

上面的 lint 和 format 命令，都需要手动执行。如果你需要在 commit 或者 push 前自动运行，那么可以参考以下 git hooks 自动运行。

因为有些小伙伴不喜欢加上 hooks 功能，所以 NextDevKit 默认没有添加 hooks 功能。

如果你是团队开发，或者需要添加 hooks 功能，可以参考以下工具：

总结

好了，到这一步，本地开发环境就准备好了。接下来就可以准备进行本地开发运行了。

end

管理代码仓库
- 新建一个 Next.js 项目
- 方式一：fork 代码仓库到你的 GitHub 账号
clone 代码
- HTTPS 方式
- SSH 方式
安装 IDE 插件
node.js 和 pnpm
Lint 和 Format
Git hooks
总结