Vue3环境配置与项目搭建指南

环境准备

确保系统已安装Node.js（建议版本16.x或更高）和npm/yarn。Node.js是运行Vue项目的基础环境，npm或yarn用于管理依赖包。可通过以下命令验证安装是否成功：

node -v
npm -v

推荐使用pnpm作为包管理器，其磁盘效率和速度优于npm/yarn。全局安装pnpm：

npm install -g pnpm

创建Vue3项目

使用Vue官方脚手架工具Vite或Vue CLI创建项目。Vite是新一代构建工具，启动速度和热更新更快。通过以下命令创建项目：

pnpm create vite my-vue-app --template vue

若选择Vue CLI，需先全局安装：

npm install -g @vue/cli
vue create my-vue-app

在交互式菜单中选择Vue3预设，配置Babel、Router等选项。项目创建完成后，进入目录安装依赖：

cd my-vue-app
pnpm install

项目结构解析

典型的Vue3项目结构包含以下核心目录和文件：

• src/：源代码目录
  • main.js：应用入口文件
  • App.vue：根组件
  • components/：可复用组件
  • views/：页面级组件
  • router/：路由配置
  • store/：状态管理（如使用Pinia/Vuex）
• public/：静态资源
• vite.config.js/vue.config.js：构建配置

配置路由

安装Vue Router4.x（Vue3专用版本）：

pnpm add vue-router@4

在src/router/index.js中配置基本路由：

import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'

const routes = [
  { path: '/', component: Home }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router

在main.js中挂载路由：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

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

状态管理

Pinia是Vue3推荐的状态管理库，比Vuex更简洁。安装Pinia：

pnpm add pinia

创建store示例（src/store/counter.js）：

import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  actions: {
    increment() {
      this.count++
    }
  }
})

在组件中使用：

<script setup>
import { useCounterStore } from '@/stores/counter'
const counter = useCounterStore()
</script>

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

组合式API实践

Vue3的核心特性组合式API（Composition API）提供更好的逻辑复用。示例组件：

<script setup>
import { ref, computed, onMounted } from 'vue'

const count = ref(0)
const doubleCount = computed(() => count.value * 2)

function increment() {
  count.value++
}

onMounted(() => {
  console.log('Component mounted')
})
</script>

<template>
  <button @click="increment">{{ count }} (Double: {{ doubleCount }})</button>
</template>

样式与预处理

支持SCSS/LESS等CSS预处理器。安装SCSS：

pnpm add -D sass

在组件中使用：

<style lang="scss" scoped>
$primary-color: #42b983;
.button {
  background: $primary-color;
}
</style>

构建与部署

开发模式启动：

pnpm dev

生产构建：

pnpm build

构建后生成dist/目录，可通过Nginx等服务器部署。示例Nginx配置：

server {
  listen 80;
  server_name yourdomain.com;
  root /path/to/dist;
  index index.html;
  location / {
    try_files $uri $uri/ /index.html;
  }
}

测试配置

添加单元测试（Vitest）：

pnpm add -D vitest @vue/test-utils

示例测试文件（tests/example.spec.js）：

import { mount } from '@vue/test-utils'
import HelloWorld from '../src/components/HelloWorld.vue'

test('displays message', () => {
  const wrapper = mount(HelloWorld, {
    props: { msg: 'Hello Vue 3' }
  })
  expect(wrapper.text()).toContain('Hello Vue 3')
})

代码规范

集成ESLint+Prettier保证代码质量。安装依赖：

pnpm add -D eslint eslint-plugin-vue @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier eslint-config-prettier

配置文件（.eslintrc.js）：

module.exports = {
  root: true,
  env: { node: true },
  extends: [
    'plugin:vue/vue3-essential',
    'eslint:recommended',
    '@vue/typescript/recommended',
    'prettier'
  ],
  rules: {
    'vue/multi-word-component-names': 'off'
  }
}

性能优化

启用Vite的代码分割和懒加载：

// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            return 'vendor'
          }
        }
      }
    }
  }
})

路由级懒加载：

const routes = [
  { 
    path: '/about',
    component: () => import('../views/About.vue')
  }
]

进阶功能

使用Teleport实现模态框：

<template>
  <button @click="showModal = true">Open</button>
  <Teleport to="body">
    <div v-if="showModal" class="modal">...</div>
  </Teleport>
</template>

自定义指令示例：

// main.js
app.directive('focus', {
  mounted(el) {
    el.focus()
  }
})

生态集成

集成Axios进行HTTP请求：

pnpm add axios

封装请求模块（src/utils/request.js）：

import axios from 'axios'
const instance = axios.create({ baseURL: 'https://api.example.com' })
export default instance

项目文档

使用Vitepress生成文档：

pnpm add -D vitepress

配置文档目录（docs/index.md）：

# Project Docs

## Getting Started
Run `pnpm dev` to start development server

持续集成

GitHub Actions示例配置（.github/workflows/deploy.yml）：

name: Deploy
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: pnpm install
      - run: pnpm build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

常见问题解决

解决SFC文件导入路径别名问题：

// vite.config.js
export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

处理Composition API中的响应式数据：

import { reactive, toRefs } from 'vue'
const state = reactive({ count: 0 })
const { count } = toRefs(state) // 保持响应式解构

版本升级

从Vue2迁移到Vue3需注意：

• 全局API改为应用实例API（createApp）
• 过滤器（filters）被移除，改用方法或计算属性
• v-model语法变更，支持多个v-model绑定
• 事件总线模式推荐改用Provide/Inject或状态管理

社区资源

推荐扩展库：

• vueuse：组合式工具集合
• element-plus：UI组件库
• nuxt.js：SSR框架
• quasar：跨平台开发框架

官方学习资源：

• Vue3文档（v3.vuejs.org）
• Vite文档（vitejs.dev）
• RFC仓库（github.com/vuejs/rfcs）