Vue 3 TypeScript项目配置指南：从零到一

在现代前端开发中，Vue 3 和 TypeScript 的结合为开发者提供了强大的工具支持和类型安全的开发体验。本文将详细讲解如何从零开始配置一个 Vue 3 + TypeScript 项目，并对关键步骤进行深入解析。

1. 环境准备

在开始之前，请确保你的开发环境已经安装了以下工具：

• Node.js（建议版本 >= 16）
• npm 或 yarn（推荐使用 npm >= 7 或 yarn >= 1.22）

可以通过以下命令检查是否已正确安装：

node -v
npm -v

如果尚未安装 Node.js，请访问 Node.js 官网 下载并安装。

2. 使用 Vue CLI 创建项目

Vue CLI 是 Vue 提供的一个脚手架工具，可以快速生成项目结构。以下是具体步骤：

2.1 安装 Vue CLI

运行以下命令安装 Vue CLI：

npm install -g @vue/cli

安装完成后，可以通过以下命令验证安装是否成功：

vue --version

2.2 创建项目

运行以下命令创建一个新的 Vue 3 项目：

vue create my-vue3-ts-project

在交互式界面中选择以下选项：

• Vue version: Manually select features
• Features: 勾选 TypeScript、Router 和 Vuex（根据需求选择）
• Use class-style component syntax?: No（推荐使用 Composition API）
• Use TypeScript with Vue 3?: Yes
• Pick a Vue Router history mode: Hash or History（推荐 History 模式）
• Configure Vuex state management?: Yes

2.3 进入项目目录

cd my-vue3-ts-project

3. 配置 TypeScript

默认情况下，Vue CLI 已经为 TypeScript 提供了基本配置。但为了更好地支持类型检查和开发体验，我们还可以进行一些额外优化。

3.1 配置 tsconfig.json

打开 tsconfig.json 文件，确保以下字段已正确配置：

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "strict": true,
    "jsx": "preserve",
    "importHelpers": true,
    "moduleResolution": "node",
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "sourceMap": true,
    "baseUrl": ".",
    "types": ["webpack-env"],
    "paths": {
      "@/*": ["src/*"]
    },
    "lib": ["esnext", "dom", "dom.iterable", "scripthost"]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}

3.2 配置全局类型声明

如果你需要扩展全局类型声明，可以在 src/shims-tsx.d.ts 中添加自定义类型。例如：

declare module '*.vue' {
  import { DefineComponent } from 'vue';
  const component: DefineComponent;
  export default component;
}

4. 配置 ESLint 和 Prettier

为了保证代码质量和一致性，我们可以集成 ESLint 和 Prettier。

4.1 安装依赖

运行以下命令安装相关依赖：

npm install eslint eslint-plugin-vue @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier eslint-config-prettier eslint-plugin-prettier --save-dev

4.2 配置 .eslintrc.js

在项目根目录下创建或编辑 .eslintrc.js 文件：

module.exports = {
  root: true,
  env: {
    node: true,
  },
  extends: [
    'plugin:vue/vue3-essential',
    'eslint:recommended',
    '@vue/typescript/recommended',
    'plugin:prettier/recommended',
  ],
  parserOptions: {
    ecmaVersion: 2020,
  },
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    '@typescript-eslint/no-explicit-any': 'off',
  },
};

4.3 配置 .prettierrc

在项目根目录下创建 .prettierrc 文件：

{
  "singleQuote": true,
  "semi": false,
  "tabWidth": 2,
  "printWidth": 100,
  "trailingComma": "es5"
}

5. 配置路由与状态管理

5.1 路由配置

在 src/router/index.ts 中配置路由：

import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router';

const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    name: 'Home',
    component: () => import('@/views/Home.vue'),
  },
  {
    path: '/about',
    name: 'About',
    component: () => import('@/views/About.vue'),
  },
];

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes,
});

export default router;

5.2 Vuex 配置

在 src/store/index.ts 中配置 Vuex：

import { createStore } from 'vuex';

export default createStore({
  state: {
    count: 0,
  },
  mutations: {
    increment(state) {
      state.count++;
    },
  },
  actions: {
    increment({ commit }) {
      commit('increment');
    },
  },
  getters: {
    doubleCount: (state) => state.count * 2,
  },
});

6. 开发与调试

6.1 启动开发服务器

运行以下命令启动开发服务器：

npm run serve

浏览器会自动打开 http://localhost:8080，你可以实时查看开发效果。

6.2 构建生产代码

当项目开发完成后，可以运行以下命令构建生产代码：

npm run build

构建后的文件会输出到 dist 目录中。

7. 扩展讨论：Composition API 示例

Vue 3 引入了 Composition API，增强了代码逻辑的可复用性。以下是一个简单的示例：

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

const message = ref('Hello, Vue 3 with TypeScript!');

onMounted(() => {
  console.log('Component mounted:', message.value);
});
</script>

<template>
  <div>{{ message }}</div>
</template>