前端项目配置文件指南：env、Node、Git 与 ESLint

前端仓库中的配置文件可以分成四类：运行环境、工具版本、版本控制和代码质量。每个文件只解决自己的问题：.env 提供环境相关值，.nvmrc 协调 Node 版本，.gitignore 忽略不应跟踪的文件，ESLint 检查代码问题；Babel 只有在构建链确实需要自定义转换时才配置。

本文合并旧版 .env、.nvmrc、.gitignore、.babelrc 与 .eslintrc 系列，并更新到 ESLint flat config 等当前写法。

目录

• .env：环境值，不是密钥保险箱
  • 环境变量安全边界
• .nvmrc 与 engines：统一 Node 版本
• .gitignore：只影响未跟踪文件
• Babel：先确认是否真的需要
• ESLint：使用 flat config
• ESLint、Prettier 与 TypeScript 分工
• 推荐的仓库基线
• 参考资料

.env：环境值，不是密钥保险箱

NODE_ENV=development
DATABASE_URL=postgresql://localhost:5432/app
API_BASE_URL=http://localhost:3000

Node.js 通过 process.env 读取环境变量，当前 Node 也提供 --env-file 等能力：

node --env-file=.env server.js

不同框架对 .env.local、.env.production、变量展开和客户端暴露有自己的规则，必须以框架文档为准。

环境变量安全边界

• .env 不应提交真实生产密钥。
• 提交 .env.example，只保留变量名和安全示例。
• 任何进入浏览器 bundle 的变量都不再是秘密。
• 密钥已经提交过时，仅加入 .gitignore 不够，必须立即轮换。
• 生产值由部署平台或密钥管理系统注入。
• 启动时验证必需变量，避免运行到业务请求才报错。

const siteUrl = process.env.NEXT_PUBLIC_SITE_URL

if (!siteUrl) {
  throw new Error("Missing NEXT_PUBLIC_SITE_URL")
}

NEXT_PUBLIC_ 等前缀表示允许进入客户端代码，不应放数据库密码或服务端 Token。

.nvmrc 与 engines：统一 Node 版本

项目根目录的 .nvmrc 通常只写一个版本：

20

使用：

nvm install
nvm use

nvm 会从当前目录向上寻找 .nvmrc。追求可重复构建时可以写具体版本；写 lts/* 更方便但会随时间解析到不同版本。

同时在 package.json 声明支持范围：

{
  "engines": {
    "node": ">=20 <23"
  }
}

.nvmrc 帮助本地 nvm 用户切换版本，engines 向包管理器和部署平台描述兼容范围。CI 和 Dockerfile 仍要显式使用匹配版本，不能假设它们自动读取 .nvmrc。

.gitignore：只影响未跟踪文件

Node／Next.js 项目常见规则：

node_modules/
.next/
dist/
coverage/
*.log
.DS_Store

.env
.env.*
!.env.example

规则要点：

• /dist 只匹配仓库根目录，dist/ 可匹配对应目录规则。
• ** 可跨多级目录匹配。
• ! 表示重新包含，但父目录被完全忽略时仍需调整父级规则。
• 仓库共享规则放 .gitignore；个人全局忽略放 Git 全局配置。

已经被 Git 跟踪的文件不会因为加入 .gitignore 自动消失。先确认影响，再从索引移除：

git rm --cached path/to/file

排查具体是哪条规则命中：

git check-ignore -v path/to/file

忽略文件不能抹掉 Git 历史中的密钥。

Babel：先确认是否真的需要

现代 Next.js、Vite 等工具通常已经包含转换链。没有自定义插件、特殊语法或库构建需求时，不要仅因为旧教程就添加 .babelrc，否则可能关闭框架优化或形成重复转换。

确实需要 Babel 时，项目级配置可使用：

{
  "presets": ["@babel/preset-env"],
  "plugins": []
}

文件命名和范围不同：

• babel.config.*：项目范围配置，monorepo 通常更合适。
• .babelrc.*：相对文件和 package 边界查找。
• package.json 的 babel 字段：适合很小的配置。

Babel 官方建议静态 JSON 配置在可行时更利于缓存和工具分析。monorepo 中应明确 root 与工作目录，不能复制单包配置后期待自动覆盖全部 workspace。

ESLint：使用 flat config

当前 ESLint 配置以 eslint.config.js、.mjs、.cjs 等 flat config 为主，导出配置对象数组：

// eslint.config.mjs
import js from "@eslint/js"
import { defineConfig } from "eslint/config"

export default defineConfig([
  js.configs.recommended,
  {
    files: ["**/*.{js,mjs,cjs}"],
    rules: {
      "prefer-const": "error",
      "no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
    },
  },
  {
    ignores: ["dist/**", ".next/**", "coverage/**"],
  },
])

React、TypeScript 和 Next.js 项目应采用对应官方或框架配置，不要只复制上面的 JavaScript 示例。

从 .eslintrc 迁移时可以使用官方迁移工具作为起点：

npx @eslint/migrate-config .eslintrc.json

生成结果仍需人工检查插件、ignore 和运行脚本。

ESLint、Prettier 与 TypeScript 分工

不要让 ESLint 和 Prettier 同时维护大量相同格式规则。完整格式化配置见 EditorConfig 与 Prettier 指南。

推荐的仓库基线

project/
├── .env.example
├── .gitignore
├── .nvmrc
├── eslint.config.mjs
├── prettier.config.mjs
├── package.json
└── tsconfig.json

CI 至少执行：

npm run lint
npm run typecheck
npm run format:check
npm test
npm run build

命令顺序可按反馈速度优化，但本地和 CI 必须使用同一套项目配置。提交阶段的自动校验可继续阅读 Husky、Commitlint 与 Git 工作流。

参考资料

• Node.js 环境变量与 .env
• nvm .nvmrc 文档
• Git gitignore 文档
• Babel 配置文件
• ESLint flat config