Anthony Fu 的 Vue3 开发规范完整解读

本文基于 antfu/skills 仓库整理翻译，全面解析 Anthony Fu 在 Vue 3 生态中的编码规范、最佳实践和工具链推荐。作为 Vue 核心团队成员、Vite 团队成员以及众多开源项目的作者（VueUse、UnoCSS、Vitest、Slidev 等），Anthony 的开发理念深刻影响了现代 Vue 开发生态。

第一部分：编码实践与工具链

代码组织原则

单一职责原则

保持文件和函数专注于单一职责。当文件超过 200-300 行时，考虑拆分：

// ❌ 避免：一个文件包含所有逻辑
// UserManager.ts (800 lines)
export class UserManager {
  validateUser() { /* 50 lines */ }
  fetchUserData() { /* 100 lines */ }
  updateUserProfile() { /* 150 lines */ }
  // ...
}

// ✅ 推荐：按职责拆分
// validation.ts
export function validateUser(user: User) { /* ... */ }

// api.ts
export function fetchUserData(id: string) { /* ... */ }

// profile.ts
export function updateUserProfile(data: ProfileData) { /* ... */ }

类型与常量分离

// types.ts
export interface User {
  id: string
  name: string
  role: UserRole
}

export type UserRole = 'admin' | 'user' | 'guest'

// constants.ts
export const DEFAULT_PAGE_SIZE = 20
export const MAX_RETRIES = 3
export const API_ENDPOINTS = {
  users: '/api/users',
  posts: '/api/posts',
} as const

// user-service.ts
import type { User, UserRole } from './types'
import { API_ENDPOINTS } from './constants'

export async function fetchUsers(): Promise<User[]> {
  const response = await fetch(API_ENDPOINTS.users)
  return response.json()
}

运行时环境标注

编写同构代码时，为环境特定的代码添加明确的注释：

// ✅ 明确标注环境依赖
// @env browser
export function getWindowSize() {
  return {
    width: window.innerWidth,
    height: window.innerHeight,
  }
}

// @env node
export function readConfigFile() {
  return fs.readFileSync('./config.json', 'utf-8')
}

// ✅ 同构代码无需标注
export function formatDate(date: Date): string {
  return date.toISOString()
}

TypeScript 最佳实践

显式返回类型

// ❌ 避免：隐式返回类型
export function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0)
}

// ✅ 推荐：显式返回类型
export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0)
}

// ✅ 复杂类型提取为类型别名
export type AsyncResult<T> = Promise<{ data: T; error: null } | { data: null; error: Error }>

export function fetchData<T>(url: string): AsyncResult<T> {
  // ...
}

避免复杂内联类型

// ❌ 避免：复杂内联类型
function processUsers(
  users: Array<{
    id: string
    profile: {
      name: string
      email: string
      settings: {
        theme: 'light' | 'dark'
        notifications: boolean
      }
    }
  }>
) {
  // ...
}

// ✅ 推荐：提取类型定义
interface UserSettings {
  theme: 'light' | 'dark'
  notifications: boolean
}

interface UserProfile {
  name: string
  email: string
  settings: UserSettings
}

interface User {
  id: string
  profile: UserProfile
}

function processUsers(users: User[]) {
  // ...
}

注释哲学

解释”为什么”而非”怎么做”

// ❌ 避免：无意义的注释
// 循环遍历用户数组
users.forEach(user => {
  // 打印用户名
  console.log(user.name)
})

// ✅ 推荐：解释为什么这样做
// 使用 setTimeout 0 延迟执行，确保 DOM 更新完成后再计算高度
setTimeout(() => {
  const height = element.offsetHeight
}, 0)

// ✅ 解释非直观的业务逻辑
// 价格计算需要先扣除折扣，再加税费，顺序不能颠倒
// 因为税费基于折后价计算（符合当地税法要求）
const finalPrice = (price - discount) * (1 + taxRate)

测试规范（Vitest）

文件组织

src/
  utils/
    format.ts          # 源代码
    format.test.ts     # 测试文件
  components/
    Button.vue
    Button.test.ts

测试结构

// format.test.ts
import { describe, it, expect } from 'vitest'
import { formatCurrency, formatDate } from './format'

describe('formatCurrency', () => {
  it('should format USD correctly', () => {
    expect(formatCurrency(1234.56, 'USD')).toBe('$1,234.56')
  })

  it('should handle zero', () => {
    expect(formatCurrency(0, 'USD')).toBe('$0.00')
  })

  it('should round to 2 decimal places', () => {
    expect(formatCurrency(1.234, 'USD')).toBe('$1.23')
  })
})

describe('formatDate', () => {
  it('should match snapshot', () => {
    const date = new Date('2024-01-15T10:30:00Z')
    expect(formatDate(date)).toMatchSnapshot()
  })
})

工具链速查

@antfu/ni - 通用包管理器命令

TypeScript 配置标准

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
    "jsx": "preserve",
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "isolatedModules": true,
    "noUncheckedIndexedAccess": true,
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

关键配置说明：

• moduleResolution: "bundler" - 适配 Vite/Rollup 等现代打包工具
• noUncheckedIndexedAccess: true - 索引访问返回 T | undefined，更安全
• strict: true - 启用所有严格类型检查

ESLint 配置

# 安装
pnpm add -D @antfu/eslint-config eslint

# 运行
pnpm run lint --fix

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

export default antfu({
  vue: true,
  typescript: true,
  formatters: {
    css: true,
    html: true,
    markdown: true,
  },
})

Git Hooks 配置

# 安装
pnpm add -D simple-git-hooks lint-staged

// package.json
{
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged"
  },
  "lint-staged": {
    "*.{js,ts,vue}": "eslint --fix"
  }
}

pnpm Catalogs 最佳实践

# pnpm-workspace.yaml
catalogs:
  # 生产依赖
  prod:
    vue: ^3.5.0
    pinia: ^2.2.0
  
  # 内联依赖（会被打包）
  inlined:
    lodash-es: ^4.17.21
  
  # 开发依赖
  dev:
    vitest: ^2.0.0
    typescript: ^5.6.0
  
  # 前端特定依赖
  frontend:
    unocss: ^0.63.0

// package.json
{
  "dependencies": {
    "vue": "catalog:prod",
    "lodash-es": "catalog:inlined"
  },
  "devDependencies": {
    "vitest": "catalog:dev",
    "unocss": "catalog:frontend"
  }
}

第二部分：Vue 3 核心规范

基于 Vue 3.5，优先使用 TypeScript 和 <script setup>

偏好设定

标准组件模板

<script setup lang="ts">
import { computed, ref, watch, onMounted } from 'vue'
import type { ComponentPublicInstance } from 'vue'

// Props 定义
interface Props {
  title: string
  count?: number
  disabled?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  count: 0,
  disabled: false,
})

// Emits 定义
interface Emits {
  update: [value: number]
  submit: [data: { name: string }]
}

const emit = defineEmits<Emits>()

// Model 双向绑定
const modelValue = defineModel<string>({ required: true })

// 响应式状态
const isLoading = ref(false)
const items = ref<Item[]>([])

// 计算属性
const displayTitle = computed(() => {
  return props.disabled ? `${props.title} (已禁用)` : props.title
})

// 侦听器
watch(() => props.count, (newVal, oldVal) => {
  console.log(`Count changed from ${oldVal} to ${newVal}`)
})

// 生命周期
onMounted(() => {
  console.log('Component mounted')
})

// 方法
function handleClick() {
  emit('update', props.count + 1)
}

// 暴露给父组件（defineExpose）
defineExpose({
  focus: () => {
    // 暴露的方法
  },
})
</script>

<template>
  <div>
    <h1>{{ displayTitle }}</h1>
    <button @click="handleClick" :disabled="disabled">
      Count: {{ count }}
    </button>
  </div>
</template>

<style scoped>
/* scoped 样式 */
</style>

关键导入速查

// 核心响应式 API
import {
  ref,           // 深层响应式
  shallowRef,    // 浅层响应式（推荐）
  reactive,      // 深层响应式对象
  shallowReactive, // 浅层响应式对象
  readonly,      // 只读代理
  computed,      // 计算属性
  watch,         // 侦听器
  watchEffect,   // 副作用侦听器
} from 'vue'

// 生命周期钩子
import {
  onMounted,
  onUpdated,
  onUnmounted,
  onBeforeMount,
  onBeforeUpdate,
  onBeforeUnmount,
} from 'vue'

// 组件通信
import {
  defineProps,
  defineEmits,
  defineModel,
  defineExpose,
  defineSlots,
  provide,
  inject,
} from 'vue'

// 工具函数
import {
  nextTick,      // 等待 DOM 更新
  toRef,         // 转换为 ref
  toRefs,        // 解构保持响应式
  unref,         // 解包 ref
  isRef,         // 判断是否 ref
  markRaw,       // 标记为非响应式
} from 'vue'

// 类型工具
import type {
  Ref,
  ComputedRef,
  ComponentPublicInstance,
  PropType,
} from 'vue'

ref vs shallowRef 性能对比

// ref - 深层响应式（递归代理所有层级）
const deepState = ref({
  user: {
    profile: {
      name: 'John',
      settings: {
        theme: 'dark',
      },
    },
  },
})

// 任何层级的修改都会触发响应
deepState.value.user.profile.settings.theme = 'light' // ✅ 响应式

// shallowRef - 浅层响应式（只代理第一层）
const shallowState = shallowRef({
  user: {
    profile: {
      name: 'John',
      settings: {
        theme: 'dark',
      },
    },
  },
})

// 只有整体替换才会触发响应
shallowState.value.user.profile.settings.theme = 'light' // ❌ 不会触发
shallowState.value = { ...shallowState.value } // ✅ 触发响应

// 性能建议：大部分场景使用 shallowRef 足够

第三部分：Vue 3 最佳实践与常见陷阱

响应式系统

计算属性

侦听器

组件通信

Props 与 Emits

模板语法

表单与 v-model

事件处理与修饰符

生命周期

插槽

Provide / Inject

组合式函数

// 示例：标准组合式函数
export function useMouse() {
  const x = ref(0)
  const y = ref(0)

  function update(event: MouseEvent) {
    x.value = event.clientX
    y.value = event.clientY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  return {
    x: readonly(x),
    y: readonly(y),
  }
}

Composition API

自定义指令

过渡与动画

KeepAlive

异步组件

TypeScript 集成

// 完整示例
import MyComponent from './MyComponent.vue'

const compRef = ref<InstanceType<typeof MyComponent>>()

onMounted(() => {
  compRef.value?.focus() // 类型安全的方法调用
})

SSR 注意事项

性能优化

SFC 特性

插件开发

第四部分：为什么选择 UnoCSS 而不是 Tailwind CSS？

核心论点：UnoCSS 是 Tailwind 的超集

UnoCSS 不是 Tailwind 的竞争者，而是增强版。通过预设系统，UnoCSS 可以 100% 兼容 Tailwind 语法：

// uno.config.ts
import { defineConfig, presetWind } from 'unocss'

export default defineConfig({
  presets: [
    presetWind(), // Tailwind CSS v3 兼容
    // 或 presetWind({ version: 4 }) // Tailwind CSS v4 兼容
  ],
})

使用 presetWind 后，所有 Tailwind 类名都能正常工作：

<!-- Tailwind 语法完全兼容 -->
<div class="flex items-center justify-between p-4 bg-blue-500 text-white rounded-lg shadow-md hover:bg-blue-600 transition">
  <span class="text-xl font-bold">完全兼容</span>
</div>

UnoCSS 的独家能力

1. 纯 CSS 图标（零 JS 运行时）

UnoCSS 通过 presetIcons 支持 10 万+ Iconify 图标，编译为纯 CSS，零 JavaScript 运行时开销：

pnpm add -D @iconify-json/carbon @iconify-json/mdi

<!-- 直接用 class 引用图标，无需导入 -->
<div class="i-carbon-logo-github text-2xl" />
<div class="i-mdi-home text-red-500" />
<button class="i-carbon-arrow-right hover:i-carbon-arrow-right-filled" />

编译结果（纯 CSS）：

.i-carbon-logo-github {
  display: inline-block;
  width: 1em;
  height: 1em;
  background: url("data:image/svg+xml;utf8,...") no-repeat;
  background-size: 100% 100%;
}

对比 Tailwind + React Icons：

• Tailwind：需要导入 React/Vue 组件，增加 bundle 体积
• UnoCSS：纯 CSS，零 JS，图标按需编译

2. 属性化模式（Attributify）

避免 class 字符串爆炸：

<!-- Tailwind：class 字符串过长 -->
<button class="bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded-lg shadow-md transition duration-300 flex items-center gap-2">
  提交
</button>

<!-- UnoCSS：属性化模式 -->
<button 
  bg="blue-500 hover:blue-600"
  text="white"
  font="bold"
  p="y-2 x-4"
  rounded="lg"
  shadow="md"
  transition
  duration="300"
  flex
  items="center"
  gap="2"
>
  提交
</button>

3. Variant Group（变体组简写）

<!-- Tailwind：重复写 hover -->
<div class="hover:bg-red-500 hover:text-white hover:scale-105">

<!-- UnoCSS：Variant Group -->
<div class="hover:(bg-red-500 text-white scale-105)">

4. 自定义规则引擎

Tailwind 需要配置复杂的插件系统，UnoCSS 支持正则和函数定义原子类：

// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  rules: [
    // 正则匹配：自定义间距
    [/^m-(\d+)$/, ([, d]) => ({ margin: `${d}px` })],
    
    // 函数定义：自定义颜色
    ['text-brand', { color: '#3b82f6' }],
    
    // 动态值：任意单位
    [/^gap-(\d+)(px|rem|em)$/, ([, num, unit]) => ({ gap: `${num}${unit}` })],
  ],
  shortcuts: {
    // 快捷组合类
    'btn-primary': 'bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600',
  },
})

5. 编译模式（Compile Class）

将多个原子类编译为一个哈希类，减少 HTML 体积：

<!-- 开发模式：原子类 -->
<div class="flex items-center gap-4 bg-blue-500 p-4">

<!-- 生产模式：编译为单个类 -->
<div class="uno-abc123">

<style>
.uno-abc123 {
  display: flex;
  align-items: center;
  gap: 1rem;
  background: #3b82f6;
  padding: 1rem;
}
</style>

对比总结

与 Anthony Fu 技术栈的协同

1. Vite 原生设计：UnoCSS 为 Vite 设计，HMR 极快
2. Nuxt 一等公民：@nuxt/unocss 开箱即用
3. 作者生态：Anthony Fu 同时是 UnoCSS 和 Iconify 的作者，工具链深度整合

完整配置示例

// uno.config.ts
import {
  defineConfig,
  presetAttributify,
  presetIcons,
  presetTypography,
  presetUno,
  presetWebFonts,
  transformerDirectives,
  transformerVariantGroup,
} from 'unocss'

export default defineConfig({
  // 预设
  presets: [
    presetUno(), // 默认预设（类似 Tailwind）
    presetAttributify(), // 属性化模式
    presetIcons({
      scale: 1.2,
      cdn: 'https://esm.sh/',
    }),
    presetTypography(), // 排版预设
    presetWebFonts({
      fonts: {
        sans: 'Inter',
        mono: 'Fira Code',
      },
    }),
  ],

  // 转换器
  transformers: [
    transformerDirectives(), // @apply 指令
    transformerVariantGroup(), // Variant Group
  ],

  // 自定义规则
  rules: [
    ['text-brand', { color: '#3b82f6' }],
  ],

  // 快捷方式
  shortcuts: {
    'btn': 'px-4 py-2 rounded inline-block cursor-pointer',
    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-600',
  },

  // 主题扩展
  theme: {
    colors: {
      brand: {
        primary: '#3b82f6',
        secondary: '#8b5cf6',
      },
    },
  },
})

安装命令：

pnpm add -D unocss
pnpm add -D @iconify-json/carbon @iconify-json/mdi

第五部分：配套工具链一览

快速开始命令

# 创建 Vue 3 项目（Vite）
pnpm create vite my-vue-app --template vue-ts

# 创建 Nuxt 3 项目
pnpm dlx nuxi@latest init my-nuxt-app

# 添加 UnoCSS
pnpm add -D unocss

# 添加 VueUse
pnpm add @vueuse/core

# 添加 Pinia
pnpm add pinia

# 添加 Vitest
pnpm add -D vitest

总结

Anthony Fu 的开发规范强调：

1. 类型安全优先：TypeScript + 显式类型定义
2. 性能意识：shallowRef > ref、避免深度侦听、虚拟滚动
3. 工具链协同：Vite + UnoCSS + Vitest 深度整合
4. 代码质量：单一职责、ESLint 自动化、Git Hooks
5. 现代化实践：Composition API、<script setup>、组合式函数

通过遵循这些规范，可以构建更快、更可维护、更具扩展性的 Vue 3 应用。

参考资料：

• antfu/skills - Anthony Fu 的技能标准文档
• Vue 3 官方文档
• UnoCSS 文档
• VueUse 文档

译者注： 本文基于 antfu/skills 仓库于 2026 年 2 月的内容整理翻译，随着生态演进，部分实践可能更新，请以官方文档为准。