从零开始用 Vue.js 搭建你的第一个实战项目

Cloud大数据

2025-12-21 00:59

阅读 1937

大家好，我是一个维护过多个开源前端项目的开发者，也写过不少技术文档。最近几年，Vue.js 几乎成了国内中小型团队的首选框架。但回想起我当初学 Vue 的时候，光看官方文档总觉得“好像懂了，又好像没懂”，尤其是面对整个生态系统时，简直一头雾水：Vue CLI、Vite、Pinia、Vue Router、组合式 API……到底该先学哪个？怎么搭配使用？

于是，我写了这篇踩坑经验分享型教程，专门面向完全零基础的新手。我会用最直白的语言，带你一步步搭建环境、理解核心概念，并完成一个可运行的小项目。全程不讲理论套话，只聚焦你能立刻上手的开发心得。

为什么选择 Vue.js？

简单说，Vue 是一个用于构建用户界面的 JavaScript 框架。它最大的特点是“渐进式”——你可以只用它渲染一个按钮，也可以用它构建复杂的单页应用（SPA）。相比 React 或 Angular，Vue 的学习曲线更平缓，中文文档完善，社区活跃，非常适合初学者入门。

我当初学的时候，第一周就做出了一个能交互的待办清单，成就感爆棚！

第一步：搭建开发环境（别跳过！）

很多新手卡在第一步：环境装不对，后面全白搭。别慌，跟着我一步步来。

推荐工具链：Vite + Vue 3

现在官方主推 Vite（读作 “veet”），它比老一代的 Vue CLI 更快、更轻量。我们直接用它创建项目。

安装步骤（需要 Node.js ≥ 16.0）

先确认你有 Node.js：
```
node -v
```
如果没有，请去 https://nodejs.org 下载 LTS 版本安装。
使用 npm 创建项目（一行命令）：
```
npm create vue@latest
```

按提示操作（建议全选 “Yes”）：

✔ Project name: … my-vue-app
✔ Add TypeScript? … No
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … Yes
✔ Add Vitest for Unit testing? … No
✔ Add an End-to-End Testing Solution? … No
✔ Add ESLint for code quality? … Yes
✔ Add Prettier for code formatting? … Yes

进入项目并启动：
```
cd my-vue-app
npm install
npm run dev
```
浏览器打开 http://localhost:5173，看到 Vue 欢迎页面就算成功！

⚠️ 常见坑：如果你用的是 Windows，且遇到权限错误，试试以管理员身份运行终端；如果是 macOS/Linux，确保 npm 全局路径配置正确。

核心概念：用大白话讲清楚

Vue 3 引入了“组合式 API”（Composition API），这是当前主流写法。别被名字吓到，其实就三件事：

1. 响应式数据：`ref` 和 `reactive`

ref：用于基本类型（字符串、数字等）
reactive：用于对象或数组

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

// 响应式变量
const count = ref(0)
const user = reactive({ name: '小明', age: 20 })

// 修改方式注意！
const increment = () => {
  count.value++ // ref 要加 .value
  user.age++    // reactive 直接改
}
</script>

<template>
  <div>
    <p>计数：{{ count }}</p>
    <p>姓名：{{ user.name }}，年龄：{{ user.age }}</p>
    <button @click="increment">+1</button>
  </div>
</template>

💡 开发心得：我早期总忘记 ref 要用 .value 访问，结果控制台报错一脸懵。记住：模板里不用 .value，JS 里要用！

2. 组件通信：props 和 emit

父组件传数据给子组件 → 用 props
子组件通知父组件 → 用 emit

父组件：

<ChildComponent :title="msg" @update-title="handleUpdate" />

子组件：

<script setup>
const props = defineProps(['title'])
const emit = defineEmits(['update-title'])

const changeTitle = () => {
  emit('update-title', '新标题')
}
</script>

3. 状态管理：Pinia（取代 Vuex）

Pinia 是 Vue 官方推荐的状态管理库，比 Vuex 简洁得多。

创建 stores/counter.js：

import { ref, defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const increment = () => count.value++
  return { count, increment }
})

在组件中使用：

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

<template>
  <p>{{ store.count }}</p>
  <button @click="store.increment">+1</button>
</template>

✅ 优势：无需 mutations/actions，函数式写法更直观。

实战：做一个简易任务清单（Todo List）

现在，我们整合前面的知识，做一个真实小项目。

功能需求

添加任务
标记完成
删除任务
统计未完成数量

步骤 1：创建组件结构

删除 src/components/ 下的默认文件，新建 TodoList.vue：

<!-- src/components/TodoList.vue -->
<script setup>
import { ref } from 'vue'

const newTask = ref('')
const tasks = ref([
  { id: 1, text: '学习 Vue', done: false },
  { id: 2, text: '写代码', done: true }
])

const addTask = () => {
  if (newTask.value.trim()) {
    tasks.value.push({
      id: Date.now(),
      text: newTask.value.trim(),
      done: false
    })
    newTask.value = ''
  }
}

const removeTask = (id) => {
  tasks.value = tasks.value.filter(t => t.id !== id)
}
</script>

<template>
  <div class="todo-app">
    <h2>我的任务清单</h2>
    
    <!-- 添加任务 -->
    <form @submit.prevent="addTask">
      <input v-model="newTask" placeholder="输入新任务..." />
      <button type="submit">添加</button>
    </form>

    <!-- 任务列表 -->
    <ul>
      <li v-for="task in tasks" :key="task.id">
        <input type="checkbox" v-model="task.done" />
        <span :class="{ done: task.done }">{{ task.text }}</span>
        <button @click="removeTask(task.id)">删除</button>
      </li>
    </ul>

    <!-- 统计 -->
    <p>未完成：{{ tasks.filter(t => !t.done).length }} / {{ tasks.length }}</p>
  </div>
</template>

<style scoped>
.done {
  text-decoration: line-through;
  color: #999;
}
.todo-app input,
.todo-app button {
  margin: 5px;
  padding: 8px;
}
</style>

步骤 2：在 App.vue 中引入

<!-- src/App.vue -->
<script setup>
import TodoList from './components/TodoList.vue'
</script>

<template>
  <div>
    <TodoList />
  </div>
</template>

步骤 3：运行看看！

保存后，浏览器会自动刷新。试试添加、勾选、删除任务——是不是很有成就感？

🛠️ 踩坑提醒：我一开始把 v-model 绑定到 task.text 上，结果发现无法编辑。后来才明白：v-model 只适用于响应式引用（如 ref），而 task 是普通对象属性，需确保 tasks 是 ref 才能触发更新。

新手常见问题 & 解决方案

问题	原因	解决方法
页面没更新	修改了非响应式数据	用 `ref`/`reactive` 包裹数据
`ref` 在模板中显示 `[object Object]`	忘记 `.value`（在 JS 中）或误用了 `.value`（在模板中）	模板里直接写 `count`，JS 里写 `count.value`
路由跳转无效	没在 `main.js` 中注册 router	确保 `createApp(App).use(router).mount(...)`
样式不生效	忘记 `scoped` 或类名写错	检查 `<style scoped>` 和 CSS 选择器
控制台报错 “xxx is not a function”	函数未正确导出或调用	检查 `defineEmits`、`defineProps` 是否在 `<script setup>` 中

下一步学习建议

恭喜你完成了第一个 Vue 项目！但这只是起点。接下来我建议：

深入组合式函数：把逻辑抽离成可复用的 composables（比如 useFetch）
学习 Vue Router：实现多页面导航（你已在项目中启用了它）
尝试 TypeScript：虽然初期复杂，但长期维护性极强
阅读官方文档：https://cn.vuejs.org 是最好的教材
参与开源：GitHub 上找 Vue 小项目提 PR，实战提升最快

最后一句真心话：不要试图一次性学完所有东西。我见过太多新手卡在“要不要先学 Webpack 再学 Vue”这种问题上。记住：先做出东西，再优化细节。代码跑起来的那一刻，你就已经超过 50% 的观望者了。

结语

这篇教程浓缩了我带新人、写文档、踩坑修复的多年经验。Vue 的魅力在于“快速看见成果”，而生态系统的成熟让你不必从零造轮子。希望你不仅能照着做出 Todo List，更能理解背后的思路——用最简单的代码，解决最实际的问题。

如果你觉得有帮助，不妨点个赞，或者去 GitHub 给你的第一个 Vue 项目建个仓库，迈出开源第一步！

加油，未来的前端工程师！🚀

标签:开发心得教程

最热最新

暂无评论

为你推荐

暂无相关推荐

从零开始用 Vue.js 搭建你的第一个实战项目

为什么选择 Vue.js？

第一步：搭建开发环境（别跳过！）

推荐工具链：Vite + Vue 3

安装步骤（需要 Node.js ≥ 16.0）

核心概念：用大白话讲清楚

1. 响应式数据：`ref` 和 `reactive`

2. 组件通信：props 和 emit

3. 状态管理：Pinia（取代 Vuex）

实战：做一个简易任务清单（Todo List）

功能需求

步骤 1：创建组件结构

步骤 2：在 App.vue 中引入

步骤 3：运行看看！

新手常见问题 & 解决方案

下一步学习建议

结语

评论 0

为你推荐

精选内容

从零开始用 Vue.js 搭建你的第一个实战项目

为什么选择 Vue.js？

第一步：搭建开发环境（别跳过！）

推荐工具链：Vite + Vue 3

安装步骤（需要 Node.js ≥ 16.0）

核心概念：用大白话讲清楚

1. 响应式数据：ref 和 reactive

2. 组件通信：props 和 emit

3. 状态管理：Pinia（取代 Vuex）

实战：做一个简易任务清单（Todo List）

功能需求

步骤 1：创建组件结构

步骤 2：在 App.vue 中引入

步骤 3：运行看看！

新手常见问题 & 解决方案

下一步学习建议

结语

评论 0

为你推荐

相关推荐

精选内容

1. 响应式数据：`ref` 和 `reactive`