1. 项目背景与核心价值Vue3和TypeScript的组合已经成为现代前端开发的黄金搭档。作为一个从零开始的学习项目这个练手项目能帮助开发者快速掌握Vue3的Composition API、响应式系统等核心特性同时体验TypeScript带来的类型安全和更好的开发体验。我在实际项目中多次使用这套技术栈发现它特别适合构建中小型应用。Vue3的性能优化和更小的包体积加上TypeScript的静态类型检查能显著提升代码质量和开发效率。这个练手项目将带你从环境搭建到核心功能实现完整走一遍开发流程。2. 环境准备与项目初始化2.1 开发工具选择对于Vue3 TypeScript开发我推荐以下工具组合VS Code轻量且对TypeScript支持极佳Volar专为Vue3设计的VS Code插件Vue DevTools调试Vue应用的浏览器插件安装完基础工具后打开终端运行npm init vuelatest vue3-ts-demo在创建向导中确保勾选TypeScript支持。这个命令会使用Vue官方的脚手架工具创建项目骨架。2.2 关键依赖解析创建完成后查看package.json中的核心依赖vue3.xVue3核心库typescriptTypeScript编译器vitejs/plugin-vueVite的Vue插件vue-tscVue的TypeScript类型检查工具提示建议将Node.js升级到最新LTS版本避免兼容性问题。我在实际项目中遇到过旧版Node导致Vite热更新失效的情况。3. 项目结构深度解析3.1 初始目录说明生成的典型项目结构如下├── src │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件 │ ├── App.vue # 根组件 │ └── main.ts # 应用入口 ├── tsconfig.json # TS配置 └── vite.config.ts # Vite配置3.2 TypeScript配置要点打开tsconfig.json有几个关键配置需要注意{ compilerOptions: { target: ESNext, module: ESNext, strict: true, jsx: preserve, moduleResolution: node, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*.ts, src/**/*.d.ts, src/**/*.tsx, src/**/*.vue] }注意strict: true会启用所有严格类型检查这对学习TypeScript很有帮助但初期可能会遇到较多类型错误。4. Vue3核心特性实践4.1 Composition API基础在src/components下创建Counter.vuescript setup langts import { ref } from vue const count ref(0) function increment() { count.value } /script template button clickincrement Count is: {{ count }} /button /template这是最基础的Composition API用法ref创建响应式变量setup语法糖简化代码完整的TypeScript类型支持4.2 组件Props类型定义改进Counter组件添加props类型检查script setup langts interface Props { initialValue?: number step?: number } const props withDefaults(definePropsProps(), { initialValue: 0, step: 1 }) const count ref(props.initialValue) function increment() { count.value props.step } /script这里展示了使用interface定义Props类型withDefaults设置默认值类型安全的props访问5. 状态管理进阶5.1 Pinia基础使用安装Pinianpm install pinia创建store/counter.tsimport { defineStore } from pinia export const useCounterStore defineStore(counter, { state: () ({ count: 0 }), actions: { increment() { this.count } } })在组件中使用script setup langts import { useCounterStore } from /stores/counter const counter useCounterStore() /script template button clickcounter.increment {{ counter.count }} /button /template5.2 类型化的StorePinia天然支持TypeScript我们可以进一步强化类型interface CounterState { count: number history: number[] } export const useCounterStore defineStore(counter, { state: (): CounterState ({ count: 0, history: [] }), actions: { increment() { this.count this.history.push(this.count) } } })6. 路由配置与类型安全6.1 Vue Router安装npm install vue-router4创建router/index.tsimport { createRouter, createWebHistory } from vue-router import HomeView from ../views/HomeView.vue const router createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: /, name: home, component: HomeView }, { path: /about, name: about, component: () import(../views/AboutView.vue) } ] }) export default router6.2 路由类型增强在src目录下创建types/router.d.tsimport vue-router declare module vue-router { interface RouteMeta { requiresAuth?: boolean title?: string } }这样可以在路由配置中使用自定义的meta字段并保持类型安全。7. 实战Todo应用开发7.1 数据结构设计创建types/todo.tsexport interface TodoItem { id: string title: string completed: boolean createdAt: Date } export type FilterType all | active | completed7.2 核心组件实现TodoList.vue的部分代码script setup langts import { ref, computed } from vue import type { TodoItem, FilterType } from /types/todo const todos refTodoItem[]([]) const filter refFilterType(all) const filteredTodos computed(() { switch (filter.value) { case active: return todos.value.filter(t !t.completed) case completed: return todos.value.filter(t t.completed) default: return todos.value } }) function addTodo(title: string) { todos.value.push({ id: crypto.randomUUID(), title, completed: false, createdAt: new Date() }) } /script8. 测试与调试技巧8.1 组件单元测试安装测试依赖npm install -D vitest vue/test-utils happy-dom创建tests/Counter.spec.tsimport { mount } from vue/test-utils import Counter from /components/Counter.vue describe(Counter, () { it(renders properly, () { const wrapper mount(Counter) expect(wrapper.text()).toContain(Count is: 0) }) it(increments count on click, async () { const wrapper mount(Counter) await wrapper.find(button).trigger(click) expect(wrapper.text()).toContain(Count is: 1) }) })8.2 调试技巧使用debugger语句配合浏览器开发者工具Vue DevTools的Composition API面板在VS Code中设置断点调试经验分享遇到类型错误时先阅读完整的错误信息。Vue3TS的错误提示通常很详细能直接定位问题所在。9. 项目优化与部署9.1 代码分割优化在vite.config.ts中添加export default defineConfig({ build: { rollupOptions: { output: { manualChunks: { vendor: [vue, pinia, vue-router] } } } } })9.2 部署准备构建生产版本npm run build生成的dist目录可以直接部署到静态托管服务如Vercel、Netlify等。10. 常见问题解决10.1 类型导入问题遇到无法找到模块错误时检查tsconfig.json中的paths配置{ compilerOptions: { paths: { /*: [src/*] } } }10.2 Vue文件类型支持确保在env.d.ts中有declare module *.vue { import type { DefineComponent } from vue const component: DefineComponent{}, {}, any export default component }10.3 响应式数据更新如果发现数据更新但视图不更新确保使用了ref或reactive检查是否直接修改了数组的length属性对于复杂对象考虑使用toRefs我在实际项目中积累的一个技巧是当遇到难以理解的类型错误时可以临时使用// ts-ignore注释掉错误但一定要后续回来解决这些类型问题这是学习TypeScript的好机会。 
长河君 · 2026/10/14 10:31:52 · 阅读 1.2k Vue3与TypeScript实战：从零构建现代化前端应用
1. 项目背景与核心价值Vue3和TypeScript的组合已经成为现代前端开发的黄金搭档。作为一个从零开始的学习项目这个练手项目能帮助开发者快速掌握Vue3的Composition API、响应式系统等核心特性同时体验TypeScript带来的类型安全和更好的开发体验。我在实际项目中多次使用这套技术栈发现它特别适合构建中小型应用。Vue3的性能优化和更小的包体积加上TypeScript的静态类型检查能显著提升代码质量和开发效率。这个练手项目将带你从环境搭建到核心功能实现完整走一遍开发流程。2. 环境准备与项目初始化2.1 开发工具选择对于Vue3 TypeScript开发我推荐以下工具组合VS Code轻量且对TypeScript支持极佳Volar专为Vue3设计的VS Code插件Vue DevTools调试Vue应用的浏览器插件安装完基础工具后打开终端运行npm init vuelatest vue3-ts-demo在创建向导中确保勾选TypeScript支持。这个命令会使用Vue官方的脚手架工具创建项目骨架。2.2 关键依赖解析创建完成后查看package.json中的核心依赖vue3.xVue3核心库typescriptTypeScript编译器vitejs/plugin-vueVite的Vue插件vue-tscVue的TypeScript类型检查工具提示建议将Node.js升级到最新LTS版本避免兼容性问题。我在实际项目中遇到过旧版Node导致Vite热更新失效的情况。3. 项目结构深度解析3.1 初始目录说明生成的典型项目结构如下├── src │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件 │ ├── App.vue # 根组件 │ └── main.ts # 应用入口 ├── tsconfig.json # TS配置 └── vite.config.ts # Vite配置3.2 TypeScript配置要点打开tsconfig.json有几个关键配置需要注意{ compilerOptions: { target: ESNext, module: ESNext, strict: true, jsx: preserve, moduleResolution: node, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*.ts, src/**/*.d.ts, src/**/*.tsx, src/**/*.vue] }注意strict: true会启用所有严格类型检查这对学习TypeScript很有帮助但初期可能会遇到较多类型错误。4. Vue3核心特性实践4.1 Composition API基础在src/components下创建Counter.vuescript setup langts import { ref } from vue const count ref(0) function increment() { count.value } /script template button clickincrement Count is: {{ count }} /button /template这是最基础的Composition API用法ref创建响应式变量setup语法糖简化代码完整的TypeScript类型支持4.2 组件Props类型定义改进Counter组件添加props类型检查script setup langts interface Props { initialValue?: number step?: number } const props withDefaults(definePropsProps(), { initialValue: 0, step: 1 }) const count ref(props.initialValue) function increment() { count.value props.step } /script这里展示了使用interface定义Props类型withDefaults设置默认值类型安全的props访问5. 状态管理进阶5.1 Pinia基础使用安装Pinianpm install pinia创建store/counter.tsimport { defineStore } from pinia export const useCounterStore defineStore(counter, { state: () ({ count: 0 }), actions: { increment() { this.count } } })在组件中使用script setup langts import { useCounterStore } from /stores/counter const counter useCounterStore() /script template button clickcounter.increment {{ counter.count }} /button /template5.2 类型化的StorePinia天然支持TypeScript我们可以进一步强化类型interface CounterState { count: number history: number[] } export const useCounterStore defineStore(counter, { state: (): CounterState ({ count: 0, history: [] }), actions: { increment() { this.count this.history.push(this.count) } } })6. 路由配置与类型安全6.1 Vue Router安装npm install vue-router4创建router/index.tsimport { createRouter, createWebHistory } from vue-router import HomeView from ../views/HomeView.vue const router createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: /, name: home, component: HomeView }, { path: /about, name: about, component: () import(../views/AboutView.vue) } ] }) export default router6.2 路由类型增强在src目录下创建types/router.d.tsimport vue-router declare module vue-router { interface RouteMeta { requiresAuth?: boolean title?: string } }这样可以在路由配置中使用自定义的meta字段并保持类型安全。7. 实战Todo应用开发7.1 数据结构设计创建types/todo.tsexport interface TodoItem { id: string title: string completed: boolean createdAt: Date } export type FilterType all | active | completed7.2 核心组件实现TodoList.vue的部分代码script setup langts import { ref, computed } from vue import type { TodoItem, FilterType } from /types/todo const todos refTodoItem[]([]) const filter refFilterType(all) const filteredTodos computed(() { switch (filter.value) { case active: return todos.value.filter(t !t.completed) case completed: return todos.value.filter(t t.completed) default: return todos.value } }) function addTodo(title: string) { todos.value.push({ id: crypto.randomUUID(), title, completed: false, createdAt: new Date() }) } /script8. 测试与调试技巧8.1 组件单元测试安装测试依赖npm install -D vitest vue/test-utils happy-dom创建tests/Counter.spec.tsimport { mount } from vue/test-utils import Counter from /components/Counter.vue describe(Counter, () { it(renders properly, () { const wrapper mount(Counter) expect(wrapper.text()).toContain(Count is: 0) }) it(increments count on click, async () { const wrapper mount(Counter) await wrapper.find(button).trigger(click) expect(wrapper.text()).toContain(Count is: 1) }) })8.2 调试技巧使用debugger语句配合浏览器开发者工具Vue DevTools的Composition API面板在VS Code中设置断点调试经验分享遇到类型错误时先阅读完整的错误信息。Vue3TS的错误提示通常很详细能直接定位问题所在。9. 项目优化与部署9.1 代码分割优化在vite.config.ts中添加export default defineConfig({ build: { rollupOptions: { output: { manualChunks: { vendor: [vue, pinia, vue-router] } } } } })9.2 部署准备构建生产版本npm run build生成的dist目录可以直接部署到静态托管服务如Vercel、Netlify等。10. 常见问题解决10.1 类型导入问题遇到无法找到模块错误时检查tsconfig.json中的paths配置{ compilerOptions: { paths: { /*: [src/*] } } }10.2 Vue文件类型支持确保在env.d.ts中有declare module *.vue { import type { DefineComponent } from vue const component: DefineComponent{}, {}, any export default component }10.3 响应式数据更新如果发现数据更新但视图不更新确保使用了ref或reactive检查是否直接修改了数组的length属性对于复杂对象考虑使用toRefs我在实际项目中积累的一个技巧是当遇到难以理解的类型错误时可以临时使用// ts-ignore注释掉错误但一定要后续回来解决这些类型问题这是学习TypeScript的好机会。