使用 Vite 创建 Vue3 项目指南

1. 环境准备

1.1 安装 Node.js（必备）

确保已安装 node.js （建议node版本18+，npm版本6+）。
或安装 nvm 可切换 node 版本。

node -v
npm -v

1.2 nvm nodejs版本管理工具

nvm 全名 node.js version management，顾名思义是一个nodejs的版本管理工具。
通过它可以安装和切换不同版本的nodejs
注意： nvm在window系统下不支持，需要使用它的替代物 nvm-windows，两者在核心使用命令上差别不大。

1.3 镜像管理工具 NRM

nrm全称npm registry manager，是npm的镜像管理工具
有时候国外的资源太慢，使用它就可以快速地在npm镜像源间快速切换。

1.3.1 安装 NRM

# 安装nrm 镜像管理工具
npm install -g nrm

1.3.2 nrm 镜像管理工具使用

# 查看镜像列表
nrm ls
# 查看当前使用的镜像
nrm current 
# 添加镜像
nrm add <名称> <远程地址或私服地址>
# 删除镜像
nrm del <名称>
# 切换镜像
nrm use <名称> 
# 测试镜像网络传输速度
nrm test <名称>
# 查看nrm版本号
nrm <-version | -V> 
# 查看nrm相关信息
nrm <-help | -h>
# 打开镜像主页
nrm home <名称> [browser]
# 上传npm包或命令程序
nrm publish [<tarball>|<folder>]

2. 创建项目

2.1 初始化项目

npm create vite@latest

2.2 进入项目目录

cd vite-project

2.3 安装依赖

npm install

2.4 初次运行

npm run dev

3. 项目结构说明

vite-project/
├── public/                 # 静态资源目录
├── src/                    # 源代码目录
│   ├── assets/            	# 项目资源文件
│   │   ├──icons/			# 字体图标文件
│   │   ├──styles/			# css样式文件
│   │   ├──images/			# 图片文件
│   ├── components/ 		# 公共组件
│   ├── constants/ 			# ts 定义枚举和常数参数
│   ├── hooks/             	# 全局使用钩子
│   ├── router/            	# 路由配置
│   ├── services/           # API接口
│   ├── stores/             # 状态管理
│   ├── types/            	# ts 类型定义文件
│   ├── utils/             	# 工具函数
│   ├── views/             	# 页面视图
│   ├── App.vue 			# 根组件
│   └── main.js            	# 入口文件
├── .gitignore             	# Git忽略文件
├── index.html            	# HTML模板
├── package.json           	# 项目配置
├── vite.config.js         	# Vite配置
└── README.md             	# 项目说明

4. 配置说明

4.1 vite.config.js

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import path from "path";

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
    },
  },
  server: {
    port: 8080,
    open: true
  }
});

4.2 package.json

{
  "name": "vite-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "ant-design-vue": "^4.2.6",
    "axios": "^1.12.2",
    "pinia": "^3.0.3",
    "vue": "^3.5.21",
    "vue-router": "^4.5.1"
  },
  "devDependencies": {
    "@types/node": "^24.7.1",
    "@vitejs/plugin-vue": "^6.0.1",
    "@vue/tsconfig": "^0.8.1",
    "typescript": "~5.8.3",
    "unplugin-vue-components": "^29.1.0",
    "vite": "^7.1.6",
    "vue-tsc": "^3.0.7"
  }
}

5. 常用依赖

5.1 路由管理

5.1.1 Router 安装

npm install vue-router

5.1.2 路由配置

// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router'

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

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

export default router

5.2 状态管理

5.2.1 Pinia 安装

状态持久化插件

npm install pinia

5.2.2 配置状态管理

// src/store/index.js
import { createPinia } from 'pinia'

const pinia = createPinia()

export default pinia

5.2.3 使用Store

// 在count.ts 中定义参数及函数
import { ref } from "vue";
import { defineStore } from "pinia";

export const useCountStore = defineStore("count", () => {
  const count = ref(1);
  const double = () => {
    count.value *= 2;
  };

  return { count, double };
});

// 在页面中使用useCountStore，setup 组合式API
import { toRefs } from "vue";
import { useCountStore } from "@/stores/count";
const countStore = useCountStore();
// 在template中使用变量count 和 函数double就可以了
const { count, double } = toRefs(countStore);

5.2.4 pinia 持久化存储插件

pinia-plugin-persistedstate是专为 Pinia 设计的持久化存储插件，用于在 Vue.js 应用中实现状态数据的本地持久化（如 localStorage 或 sessionStorage）。

• 安装插件

# 安装插件
npm install pinia-plugin-persistedstate

• 全局配置

// main.ts
import { createPinia } from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);

• 插件使用

// user.ts 默认使用 localStorage，会直接把当前参数存放到缓存中
export const useUserStore = defineStore('user', () => {
	const token = ref();
	return { token }
},
{
  persist: true
});

5.3 HTTP 请求

5.3.1 Axios 安装

npm install axios

5.3.2 配置HTTP请求

// src/utils/request.js
import axios from "axios";

/**
 * 创建 axios 请求实例
 * 设置 axios 默认配置
 */
const axiosRequest = axios.create({
  baseURL: "/api",
  timeout: 5000,
});

/**
 * request 请求拦截器
 * header 统一添加 token
 * header 统一添加其它参数
 */
axiosRequest.interceptors.request.use(
  (config) => {
    // 添加 token
    // config.headers.Authorization = 'Bearer ' + getToken()
    // 添加其它参数
    // config.headers.other = 'other'
    return config;
  },
  (error) => {
    return Promise.reject(error);
  }
);

/**
 * response 响应拦截器
 * 统一处理错误
 * 统一处理返回数据
 */
axiosRequest.interceptors.response.use(
  (response) => {
    // 统一处理错误
    if (response.status !== 200) {
      return Promise.reject(response.data.message);
    }
    // 统一处理返回数据
    return response;
  },
  (error) => {
    return Promise.reject(error);
  }
);

/**
 * 统一封装请求实例
 * @param url 请求地址
 * @param params 请求参数
 * @param options 请求配置
 */
const request = async <T = any>(
  url: string,
  params?: any,
  options?: any
): Promise<T | undefined> => {
  const { method = "get" } = options || {};
  try {
    const response = await axiosRequest({
      url,
      method,
      [method === "get" ? "params" : "data"]: params,
    });
    if (response) {
      return response.data;
    }
    return undefined;
  } catch (error) {
    console.log(error);
    return undefined;
  }
};

export default request;

5.3.4 使用 axios

// src/services/demo.ts
import request from "@/utils/request";

type DogImg = {
  message: string;
  status: string;
};
export const getDogImg = () => {
  return request<DogImg>("https://dog.ceo/api/breeds/image/random");
};

5.4 UI 组件库

5.4.1 安装 ant-design-vue

npm install ant-design-vue --save

5.4.2 引入配置

// 在 main.ts 文件中引入css样式
import "ant-design-vue/dist/reset.css";

// 在 vue 页面中引用即可正常使用
import { Button } from 'ant-design-vue';

5.4.3 自动按需引入组件（优化组件使用，非必需）

unplugin-vue-components 是一款基于 unplugin 生态的 Vue 组件自动导入插件，支持 Vue 2 和 Vue 3，并兼容 Vite、Webpack、Rollup 等多种构建工具。其核心功能是通过静态分析模板代码，实现组件的按需自动导入和注册，从而减少手动导入的繁琐操作并优化打包体积。

# 安装 unplugin-vue-components 插件
npm install unplugin-vue-components -D

// vite.config.ts
import { defineConfig } from "vite";
import Components from "unplugin-vue-components/vite";
import { AntDesignVueResolver } from "unplugin-vue-components/resolvers";

// https://vite.dev/config/
export default defineConfig({
  plugins: [
  	// ...
    Components({
      resolvers: [
        AntDesignVueResolver({
          importStyle: false,
        }),
      ],
    }),
  ]
});

后续直接使用组件就可以了

5.5 样式预处理器

npm install less --save-dev

6. 开发规范

6.1 文件命名规范

• 组件文件：PascalCase命名，如UserInfo.vue
• 工具文件：camelCase命名，如userLogin.js
• 样式文件：kebab-case命名，如common-style.less

6.2 代码规范

• 使用 ESLint 进行代码检查
• 使用 Prettier 进行代码格式化
• 遵循 Vue3 组合式 API 规范

6.3 Git 提交规范

• feat：新功能
• fix：修复 Bug
• docs：文档更新
• style：代码格式调整
• refactor：代码重构
• test：测试相关
• chore：构建过程或辅助工具的变动

7. 开发流程

7.1 启动开发服务器

npm run dev

7.2 构建生产环境

npm run build

7.3 预览生产构建

npm run preview

8. 常见问题解决

8.1 路径别名配置

在vite.config.ts中配置路径别名，使用@代替src目录

8.2 跨域问题

在vite.config.ts中配置代理

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true
    }
  }
}

8.3 环境变量配置

创建.env文件

VITE_API_BASE_URL=/api

9. 参考资料

Vite官方文档：https://vitejs.dev/
Vue3官方文档：https://v3.vuejs.org/
Vue Router文档：https://router.vuejs.org/
Pinia文档：https://pinia.vuejs.org/