Vue 生态系统与工具链

# 全局安装
npm install -g @vue/cli

# 交互式创建项目
vue create my-project

# 图形化界面创建
vue ui

# 启动开发服务器 / 构建
npm run serve
npm run build

// vue.config.js
const { defineConfig } = require('@vue/cli-service')

module.exports = defineConfig({
  transpileDependencies: true,
  publicPath: process.env.NODE_ENV === 'production' ? '/app/' : '/',
  productionSourceMap: false,
  devServer: {
    port: 8080,
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        pathRewrite: { '^/api': '' }
      }
    }
  },
  chainWebpack: (config) => {
    // 自定义 webpack 配置，例如设置别名
    config.resolve.alias.set('@', require('path').resolve(__dirname, 'src'))
  }
})

# 创建 Vue 3 + TypeScript 项目
npm create vite@latest my-app -- --template vue-ts

cd my-app
npm install
npm run dev      # 启动开发服务器
npm run build    # 生产构建
npm run preview  # 本地预览构建产物

// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import { resolve } from 'path'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

// mode 用于区分 development / production / staging
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    plugins: [
      vue(),
      vueJsx(),
      // 自动导入 ref / computed / watch 等 API，无需手动 import
      AutoImport({
        imports: ['vue', 'vue-router', 'pinia'],
        resolvers: [ElementPlusResolver()],
        dts: 'src/auto-imports.d.ts'
      }),
      // 自动按需注册组件
      Components({
        resolvers: [ElementPlusResolver()],
        dts: 'src/components.d.ts'
      })
    ],
    resolve: {
      alias: {
        '@': resolve(__dirname, 'src'),
        '@components': resolve(__dirname, 'src/components'),
        '@utils': resolve(__dirname, 'src/utils')
      }
    },
    css: {
      preprocessorOptions: {
        scss: {
          // 全局注入变量，无需每个文件单独 import
          additionalData: `@use "@/styles/variables.scss" as *;`
        }
      }
    },
    server: {
      port: 5173,
      open: true,
      proxy: {
        '/api': {
          target: env.VITE_API_BASE || 'http://localhost:3000',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, '')
        }
      }
    },
    build: {
      target: 'es2015',
      sourcemap: false,
      chunkSizeWarningLimit: 1500,
      rollupOptions: {
        output: {
          // 手动拆包，把大依赖单独打包，利于长期缓存
          manualChunks: {
            vue: ['vue', 'vue-router', 'pinia'],
            elementPlus: ['element-plus'],
            echarts: ['echarts']
          }
        }
      }
    }
  }
})

# .env.development
VITE_API_BASE=http://localhost:3000
VITE_APP_TITLE=我的应用（开发）

# .env.production
VITE_API_BASE=https://api.example.com
VITE_APP_TITLE=我的应用

// src/config/index.ts
export const API_BASE = import.meta.env.VITE_API_BASE
export const APP_TITLE = import.meta.env.VITE_APP_TITLE
export const IS_PROD = import.meta.env.PROD

// src/router/index.ts
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router'

const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'Home',
    // 懒加载：打包时该组件会被单独拆成一个 chunk，按需加载
    component: () => import('@/views/Home.vue'),
    meta: { title: '首页', requiresAuth: false }
  },
  {
    path: '/dashboard',
    name: 'Dashboard',
    component: () => import('@/views/Dashboard.vue'),
    meta: { title: '控制台', requiresAuth: true },
    children: [
      {
        path: 'profile',
        name: 'Profile',
        component: () => import('@/views/Profile.vue'),
        meta: { title: '个人中心' }
      }
    ]
  },
  {
    // 动态路由：/user/123 -> params.id === '123'
    path: '/user/:id',
    name: 'User',
    component: () => import('@/views/User.vue'),
    props: true // 将路由参数作为 props 传入组件
  },
  {
    // 404 兜底
    path: '/:pathMatch(.*)*',
    name: 'NotFound',
    component: () => import('@/views/NotFound.vue')
  }
]

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
  scrollBehavior(to, from, savedPosition) {
    // 前进后退时恢复滚动位置，否则回到顶部
    return savedPosition || { top: 0 }
  }
})

export default router

// src/router/guards.ts
import router from './index'
import { useUserStore } from '@/stores/user'

router.beforeEach((to, from, next) => {
  // 动态设置页面标题
  document.title = (to.meta.title as string) || import.meta.env.VITE_APP_TITLE

  const userStore = useUserStore()

  if (to.meta.requiresAuth && !userStore.isLoggedIn) {
    // 未登录，重定向到登录页并携带回跳地址
    next({ name: 'Login', query: { redirect: to.fullPath } })
  } else {
    next()
  }
})

router.afterEach((to) => {
  // 可在此处埋点上报页面浏览
  console.log('[route] navigated to', to.fullPath)
})

<script setup lang="ts">
import { useRoute, useRouter } from 'vue-router'

const route = useRoute()   // 当前路由信息（响应式）
const router = useRouter()  // 路由实例，用于编程式跳转

// 读取动态参数
const userId = route.params.id

function goToDetail(id: number) {
  router.push({ name: 'User', params: { id } })
}

function goBack() {
  router.back()
}
</script>

<template>
  <div>
    <p>当前用户 ID：{{ userId }}</p>
    <button @click="goToDetail(42)">查看用户 42</button>
    <button @click="goBack">返回</button>
  </div>
</template>

// 根据后端返回的菜单动态注册路由
function addDynamicRoutes(menus: MenuItem[]) {
  menus.forEach((menu) => {
    router.addRoute('Dashboard', {
      path: menu.path,
      name: menu.name,
      component: () => import(`@/views/${menu.component}.vue`),
      meta: { title: menu.title, requiresAuth: true }
    })
  })
}

// src/stores/counter.ts
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
    name: 'Vue'
  }),
  getters: {
    doubleCount: (state) => state.count * 2
  },
  actions: {
    increment() {
      this.count++
    },
    async fetchInitial() {
      const res = await fetch('/api/counter')
      this.count = (await res.json()).count
    }
  }
})

// src/stores/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { login as loginApi, getUserInfo } from '@/api/user'

export const useUserStore = defineStore('user', () => {
  // state
  const token = ref<string>(localStorage.getItem('token') || '')
  const userInfo = ref<UserInfo | null>(null)

  // getters
  const isLoggedIn = computed(() => !!token.value)
  const userName = computed(() => userInfo.value?.name ?? '游客')

  // actions
  async function login(username: string, password: string) {
    const { token: newToken } = await loginApi(username, password)
    token.value = newToken
    localStorage.setItem('token', newToken)
    await loadUserInfo()
  }

  async function loadUserInfo() {
    userInfo.value = await getUserInfo()
  }

  function logout() {
    token.value = ''
    userInfo.value = null
    localStorage.removeItem('token')
  }

  return { token, userInfo, isLoggedIn, userName, login, loadUserInfo, logout }
})

<script setup lang="ts">
import { storeToRefs } from 'pinia'
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()
// 直接解构会丢失响应性，必须用 storeToRefs
const { userName, isLoggedIn } = storeToRefs(userStore)
// 方法可以直接解构
const { login, logout } = userStore
</script>

<template>
  <div>
    <span v-if="isLoggedIn">你好，{{ userName }}</span>
    <button v-else @click="login('admin', '123456')">登录</button>
    <button v-if="isLoggedIn" @click="logout">退出</button>
  </div>
</template>

npm install pinia-plugin-persistedstate

// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
import App from './App.vue'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)

createApp(App).use(pinia).mount('#app')

// 在 store 中开启持久化（Option Store 写法）
export const useSettingStore = defineStore('setting', {
  state: () => ({ theme: 'light', lang: 'zh-CN' }),
  persist: {
    key: 'app-setting',
    storage: localStorage,
    // 只持久化部分字段
    pick: ['theme', 'lang']
  }
})

// src/utils/request.ts
import axios, { type AxiosInstance, type AxiosRequestConfig, type AxiosResponse } from 'axios'
import { ElMessage } from 'element-plus'
import { useUserStore } from '@/stores/user'

const service: AxiosInstance = axios.create({
  baseURL: import.meta.env.VITE_API_BASE,
  timeout: 15000,
  headers: { 'Content-Type': 'application/json' }
})

// 请求拦截器：注入 token
service.interceptors.request.use(
  (config) => {
    const userStore = useUserStore()
    if (userStore.token) {
      config.headers.Authorization = `Bearer ${userStore.token}`
    }
    return config
  },
  (error) => Promise.reject(error)
)

// 响应拦截器：统一解包与错误处理
service.interceptors.response.use(
  (response: AxiosResponse) => {
    const res = response.data
    if (res.code !== 0) {
      ElMessage.error(res.message || '请求出错')
      // token 失效，强制登出
      if (res.code === 401) {
        useUserStore().logout()
        window.location.href = '/login'
      }
      return Promise.reject(new Error(res.message || 'Error'))
    }
    return res.data
  },
  (error) => {
    const status = error.response?.status
    const msgMap: Record<number, string> = {
      400: '请求参数错误',
      403: '没有权限',
      404: '资源不存在',
      500: '服务器内部错误',
      502: '网关错误',
      503: '服务不可用'
    }
    ElMessage.error(msgMap[status] || error.message || '网络异常')
    return Promise.reject(error)
  }
)

// 泛型封装，让调用处拿到正确的返回类型
export function request<T = unknown>(config: AxiosRequestConfig): Promise<T> {
  return service(config) as unknown as Promise<T>
}

export default service

// src/api/user.ts
import { request } from '@/utils/request'

export interface LoginResult {
  token: string
}

export interface UserInfo {
  id: number
  name: string
  roles: string[]
}

export function login(username: string, password: string) {
  return request<LoginResult>({
    url: '/auth/login',
    method: 'post',
    data: { username, password }
  })
}

export function getUserInfo() {
  return request<UserInfo>({ url: '/user/info', method: 'get' })
}

npm install element-plus
npm install -D unplugin-vue-components unplugin-auto-import

<template>
  <el-form :model="form" label-width="80px">
    <el-form-item label="用户名">
      <el-input v-model="form.name" placeholder="请输入" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="onSubmit">提交</el-button>
    </el-form-item>
  </el-form>
</template>

<script setup lang="ts">
import { reactive } from 'vue'
const form = reactive({ name: '' })
function onSubmit() {
  console.log('submit', form.name)
}
</script>

npm install @vueuse/core

<script setup lang="ts">
import {
  useMouse,
  useLocalStorage,
  useDark,
  useToggle,
  useDebounceFn,
  useWindowSize,
  onClickOutside
} from '@vueuse/core'
import { ref } from 'vue'

// 响应式鼠标坐标
const { x, y } = useMouse()

// 自动同步到 localStorage 的响应式变量
const name = useLocalStorage('user-name', '游客')

// 暗黑模式切换
const isDark = useDark()
const toggleDark = useToggle(isDark)

// 响应式窗口尺寸
const { width, height } = useWindowSize()

// 防抖函数
const onSearch = useDebounceFn((keyword: string) => {
  console.log('搜索：', keyword)
}, 300)

// 点击元素外部关闭弹层
const modal = ref<HTMLElement | null>(null)
onClickOutside(modal, () => console.log('点击了外部'))
</script>

<template>
  <div>
    <p>鼠标位置：{{ x }}, {{ y }}</p>
    <p>窗口尺寸：{{ width }} x {{ height }}</p>
    <input v-model="name" placeholder="名字会被自动记住" />
    <button @click="toggleDark()">切换主题（当前：{{ isDark ? '暗' : '亮' }}）</button>
  </div>
</template>

npm install -D vitest @vue/test-utils jsdom @vitest/coverage-v8

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: { '@': resolve(__dirname, 'src') }
  },
  test: {
    globals: true,
    environment: 'jsdom',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html'],
      thresholds: { lines: 80, functions: 80, branches: 75 }
    }
  }
})

<!-- src/components/Counter.vue -->
<script setup lang="ts">
import { ref } from 'vue'
const props = defineProps<{ initial?: number }>()
const count = ref(props.initial ?? 0)
const emit = defineEmits<{ change: [value: number] }>()
function increment() {
  count.value++
  emit('change', count.value)
}
</script>

<template>
  <button @click="increment">count is {{ count }}</button>
</template>

// src/components/__tests__/Counter.spec.ts
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import Counter from '../Counter.vue'

describe('Counter', () => {
  it('渲染初始值', () => {
    const wrapper = mount(Counter, { props: { initial: 5 } })
    expect(wrapper.text()).toContain('count is 5')
  })

  it('点击后递增并触发 change 事件', async () => {
    const wrapper = mount(Counter, { props: { initial: 0 } })
    await wrapper.find('button').trigger('click')
    expect(wrapper.text()).toContain('count is 1')
    expect(wrapper.emitted('change')?.[0]).toEqual([1])
  })
})

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

npm install -D eslint eslint-plugin-vue @vue/eslint-config-typescript \
  @vue/eslint-config-prettier prettier

// .eslintrc.cjs
module.exports = {
  root: true,
  env: { browser: true, node: true, es2022: true },
  extends: [
    'plugin:vue/vue3-recommended',
    'eslint:recommended',
    '@vue/eslint-config-typescript',
    '@vue/eslint-config-prettier'
  ],
  parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
  rules: {
    'vue/multi-word-component-names': 'off',
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    '@typescript-eslint/no-explicit-any': 'warn'
  }
}

// .prettierrc.json
{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "none",
  "arrowParens": "always"
}

// package.json 片段
{
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "prettier --write"]
  }
}

npm install -D rollup-plugin-visualizer

// vite.config.ts 中加入
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  plugins: [
    vue(),
    // 构建后自动打开体积可视化报告
    visualizer({ open: true, gzipSize: true, brotliSize: true })
  ]
})

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist