Vue3.0 + Vite + Ts项目配置

本系列专栏，主要用于记录Vue3.0+Vite+Ts项目的开发以及相关项目的配置，持续更新！

Vue3.0、Vite、Ts现在都是市面上主流的前端框架，学会创建项目是基础中的基础。

创建项目过程中，难免会遇到一些疑难杂症，这篇文章就详细的讲解了创建项目过程中可能会踩的坑。话不多说，发车！

文末附源码获取地址！文末附源码获取地址！文末附源码获取地址！

一、检查安装环境

确保电脑已经安装了node以及npm

-- 检查node的版本号
node -v

-- 检查npm的版本号
npm -v

二、创建项目

2.1 打开你自己的工作目录，cmd打开命令窗口

2.2 输入命令

npm init vite@latest hs-vue3-element-admin --template vue-ts

hs-vue3-element-admin：项目名称

执行后，出现一下界面就是创建成功。

三、项目基础配置

3.1 用VSCode打开项目，并安装项目依赖，检查项目能否正常运行

Ctrl + Shift + ~ 快捷键，打开运行终端

这里有些小伙伴可能会报错：XXX is not a function，大概率就是你的node版本有问题，直接升级到最新就可以。

3.2 项目配置别名

别名的配置，对于我们后续的开发是非常重要的，能帮我们省去一堆麻烦

3.2.1 安装必要的依赖

安装依赖

npm install @types/node --save-dev

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
})

3.2.2 配置tsconfig.json

这一步非常重要！非常重要！非常重要！

除了配置别名外，我们需要在这里配置baseUrl，相对路径的访问会不成功(或者文件爆红)

include：在vue文件中我们会用到各种xxx.ts，这个配置就是为了让vue识别.ts文件以及让ts识别导入的vue文件

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
    },
    "types": ["vite/client"]
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"],
  "exclude": ["dist", "target", "node_modules"]
}

3.3.3 配置 vite-env.d.ts

/// <reference types="vite/client" />

// 解决Vue文件导入报红
declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent<{}, {}, any>
  export default component
}


// 支持别名路径类型识别
declare module '@/*' {
  const _default: any;
  export default _default
}

1. 在Ts文件中，导入vue文件会爆红，原因是Ts无法识别.vue后缀的文件，这里需要加上配置

2. 文件中可能无法识别到@符合，虽然能正常使用，但文件会一直爆红，看着难受

3.3.4 验证配置是否生效

App.vue

浏览器能够正常显示，配置正常。

大家可以每配置一步，然后到App.vue中验证一下，直接使用@访问，会出现什么情况，这里当做一个小疑问，留给大家自己手动去验证！

上面的所有步骤配置完，如果能直接通过Ctrl + 鼠标左键进入对应的文件，就是配置成功！

3.3 项目基础环境配置

我们通常会有两套环节：本地的测试环境以及正式的环境（也就是上线的配置）

Vue也支持多环境配置，只需要在vue项目的根目录，创建.env文件即可(与src同目录)

3.3.1 .env文件的配置

 .env 格式的命名方式可以多种多样，只需要文件开头为.env ，后面的名字你想怎样都可以，如：.env.dev/ .env.prod/ .env.test

特殊的命名方式：

• .env.pord 打包 vue 会压缩代码
• .env 默认 vue 配置文件
• .env.***.local git 会忽略

3.3.2 .env文件的配置说明

.env文件我们能配置什么？怎么让项目启动的时候，启动对应的.env文件，这些我们一步一步来

1）.env文件我们能配置什么？

在.env配置文件里面，我们可以定义一些想全局使用的配置，如：端口，前端访问链接等等

2）怎么访问到在.env配置的变量？

使用 import.meta.env.变量名 即可访问对应的配置属性

这里需要注意一个点，需要在 tsconfig.json 定义你的模块model属性为以下几种，否则会报错：

仅当 '--module' 选项为 'es2020'、'es2022'、'esnext'、'system'、'node16'、'node18'、'node20' 或 'nodenext' 时，才允许使用 'import.meta' 元属性。

但是，在 tsconfig.json 定义之后，可能会衍生出另外一个问题，上面的 vite-env.d.ts 配置中，下面的引用报错了

import type { DefineComponent } from 'vue'

报错信息：

找不到模块“vue”。你的意思是要将 "moduleResolution" 选项设置为 "nodenext"，还是要将别名添加到 "paths" 选项中?

这个报错，需要我们在 tsconfig.json，加入配置属性："moduleResolution": "node",

所以 tsconfig.json 的完整配置：

{
  "compilerOptions": {
    "module": "esnext",
    "target": "esnext",
    "moduleResolution": "node",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
    }
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue", "types/**/*.d.ts",],
}

3）怎么让对应的.env文件生效

在 package.json 中，我们可以修改scripts属性的配置，方便我们在启动环境的时候，指定对应的配置文件

先来区分两个命令：
build：顾名思义，就是打包
serve：服务，就是我们前面说的，启动项目使用

两个命令后面接的配置，就是 .env.xxx中 xxx 的名字
如：.env.test   build:test serve:test

4）例子演示

在项目下创建了两个.env配置文件：

package.json

  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview",
    "build:test": "node --max_old_space_size=4096 ./node_modules/vite/bin/vite.js build --mode test",
    "serve:test": "vite preview --mode test",
    "build:prod": "node --max_old_space_size=4096 ./node_modules/vite/bin/vite.js build --mode prod",
    "serve:prod": "vite preview --mode prod"
  }

.env.test

#请求路径
VITE_API_BASE_URL= 'http://localhost:8888'

# 前端启动端口
VITE_PORT=7778

.env.prod

#请求路径
VITE_BASE_URL= 'http://localhost:8788'

# 前端启动端口
VITE_PORT='8789'

HelloWorld.vue加打印：

启动项目分别验证：

npm run serve:test 在运行这个命令前，我们必须先试用 npm run build:test 构建项目，否则会报错

说明的确是打包了我们的.env.test配置文件

说明：

npm run build:test 打包项目，会生成 dist 目录，而且 并不会打包.env.test配置文件，而是会自动将文件中以VITE开头的变量，自动注入到环境。

四、整个项目的配置以及项目获取地址

4.1 package.json

{
  "name": "hs-vue3-element-admin-manger",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite --mode test",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview",
    "build:test": "node --max_old_space_size=4096 ./node_modules/vite/bin/vite.js build --mode test",
    "serve:test": "vite preview --mode test",
    "build:prod": "node --max_old_space_size=4096 ./node_modules/vite/bin/vite.js build --mode prod",
    "serve:prod": "vite preview --mode prod"
  },
  "dependencies": {
    "vue": "^3.5.18"
  },
  "devDependencies": {
    "@types/node": "^24.3.0",
    "@vitejs/plugin-vue": "^6.0.1",
    "@vue/tsconfig": "^0.7.0",
    "typescript": "~5.8.3",
    "vite": "^7.1.2",
    "vue-tsc": "^3.0.5"
  }
}

4.2 tsconfig.json

{
  "compilerOptions": {
    "module": "esnext",
    "target": "esnext",
    "moduleResolution": "node",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
    }
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue", "types/**/*.d.ts",],
}

4.3 vite.config.ts

import { UserConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
import { loadEnv, ConfigEnv } from 'vite'


// https://vite.dev/config/
// export default defineConfig({
//   plugins: [vue()],
//   resolve: {
//     alias: {
//       '@': path.resolve(__dirname, 'src')
//     }
//   },
//   server: {
//     port: import.meta.env.VITE_PORT
//   }
// })
export default ({mode}: ConfigEnv): UserConfig => {
  let env = {} as any
  env = loadEnv(mode, process.cwd());

  return {
    plugins: [vue()],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      }
    },
    server: {
      port: env.VITE_PORT
    }
  }
}

4.4 App.vue

<script setup lang="ts">
import HelloWorld from '@/components/HelloWorld.vue'
</script>

<template>
  <div>
    <a href="https://vite.dev" target="_blank">
      <img src="/vite.svg" class="logo" alt="Vite logo" />
    </a>
    <a href="https://vuejs.org/" target="_blank">
      <img src="./assets/vue.svg" class="logo vue" alt="Vue logo" />
    </a>
  </div>
  <HelloWorld msg="Vite + Vue" />
</template>

<style scoped>
.logo {
  height: 6em;
  padding: 1.5em;
  will-change: filter;
  transition: filter 300ms;
}
.logo:hover {
  filter: drop-shadow(0 0 2em #646cffaa);
}
.logo.vue:hover {
  filter: drop-shadow(0 0 2em #42b883aa);
}
</style>

4.5 HelloWorld.vue

<script setup lang="ts">
import { ref } from 'vue'

defineProps<{ msg: string }>()

const count = ref(0)

const test = () => {
  console.log(import.meta.env.VITE_API_BASE_URL);
}

</script>

<template>
  <h1>{{ msg }}</h1>

  <div class="card">
    <button type="button" @click="test">count is {{ count }}</button>
    <p>
      Edit
      <code>components/HelloWorld.vue</code> to test HMR
    </p>
  </div>

  <p>
    Check out
    <a href="https://vuejs.org/guide/quick-start.html#local" target="_blank"
      >create-vue</a
    >, the official Vue + Vite starter
  </p>
  <p>
    Learn more about IDE Support for Vue in the
    <a
      href="https://vuejs.org/guide/scaling-up/tooling.html#ide-support"
      target="_blank"
      >Vue Docs Scaling up Guide</a
    >.
  </p>
  <p class="read-the-docs">Click on the Vite and Vue logos to learn more</p>
</template>

<style scoped>
.read-the-docs {
  color: #888;
}
</style>

好了，Vue3.0项目的创建以及相关的基础配置大概就这么多！列车到站！

我是写代码的小和尚，平时喜欢写写博客，如果我的文章对您有所帮助，麻烦点赞收藏一下吧！让更多的人看见，谢谢大家！  

源码获取地址：https://pan.quark.cn/s/bb1a9c6c967b

修复说明：

1 .env.test配置有误，修改一下(2025.08.29)