antfu

编码实践

代码组织

• 单一职责：每个源文件应有清晰、集中的范围/目的
• 拆分大文件：当文件变得庞大或处理过多关注点时，进行拆分
• 类型分离：始终将类型和接口分离到 types.ts 或 types/*.ts 中
• 常量提取：将常量移至专用的 constants.ts 文件

运行时环境

• 优先同构代码：尽可能编写运行时无关的代码，使其能在 Node、浏览器和 Worker 中工作
• 明确运行时指示：当代码特定于环境时，在文件顶部添加注释：

// @env node
// @env browser

TypeScript

• 显式返回类型：尽可能声明返回类型
• 避免复杂内联类型：将复杂类型提取到专用的 type 或 interface 声明中

显式性

偏好显式、可追溯的代码，而非隐式的“魔法”。读者（人类或代理）应能无需运行工具即可追踪每个名称的来源。

• 显式导入：优先使用显式的 import 语句。避免自动导入——当框架提供自动导入时（如 Nuxt/Nitro），在新项目中将其关闭（参见 app-development）。
• 默认不使用路径别名：使用相对导入（./foo、../bar）。仅当项目中已配置路径别名（@/、~/、#imports 等）时才使用；不要为全新代码引入新的别名。

注释

• 避免不必要的注释：代码应自解释
• 解释“为什么”而非“怎么做”：注释应描述原因或意图，而非代码做了什么

测试（Vitest）

• 测试文件：foo.ts → foo.test.ts（同一目录）
• 使用 describe/it API（而非 test）
• 对复杂输出使用 toMatchSnapshot
• 对语言特定的快照使用 toMatchFileSnapshot 并指定显式路径

---

工具选择

@antfu/ni 命令

命令	描述
ni	安装依赖
ni <pkg> / ni -D <pkg>	添加依赖 / 开发依赖
nr <script>	运行脚本
nu	升级依赖
nun <pkg>	卸载依赖
nci	干净安装（pnpm i --frozen-lockfile）
nlx <pkg>	执行包（npx）

检查 npm 包版本

使用 fast-npm-meta 查找包的最新版本——它查询一个小型元数据端点，而不是下载完整的注册表负载（每个包可能达数兆字节）。

nlx fast-npm-meta version vite              # 7.3.1
nlx fast-npm-meta version "nuxt@^3.5"       # 3.5.22 — 范围感知
nlx fast-npm-meta version vite nuxt vue     # 同时查询多个
nlx fast-npm-meta version vite --json       # JSON 格式用于脚本
nlx fast-npm-meta full vite                 # 完整版本列表 + dist-tags

当只需要最新版本时，优先使用此命令而非 npm view <pkg> version，也优于直接从注册表读取 package.json。

TypeScript 配置

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

ESLint 设置

// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu()

完成任务时，运行 pnpm run lint --fix 来格式化代码并修复编码风格。

详细配置选项：antfu-eslint-config

Git Hooks

{
  "simple-git-hooks": {
    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
  },
  "lint-staged": { "*": "eslint --fix" },
  "scripts": {
    "prepare": "npx simple-git-hooks"
  }
}

pnpm Catalogs

在 pnpm-workspace.yaml 中使用命名目录进行版本管理：

目录	用途
prod	生产依赖
inlined	打包器内联依赖
dev	开发工具（linter、打包器、测试）
frontend	前端库

避免使用默认目录。目录名称可根据项目需求调整。

---

参考

主题	描述	参考
ESLint 配置	框架支持、格式化器、规则覆盖、VS Code 设置	antfu-eslint-config
项目设置	.gitignore、GitHub Actions、VS Code 扩展	setting-up
应用开发	Vue/Nuxt/UnoCSS 约定、自动导入控制、Storybook 组件测试	app-development
库开发	tsdown 打包、纯 ESM 发布	library-development
Monorepo	pnpm workspaces、集中化别名、Turborepo	monorepo