2、环境搭建：创建Vue3项目、安装Pinia依赖、在main.js中注册Pinia、项目结构规划

2.1 创建Vue3项目——选对工具，事半功倍

说实话，很多新手在环境搭建这一步就栽了跟头。我见过太多人因为Node版本不对、脚手架选错，折腾半天还没开始写代码。咱们直接上最稳的方案。

我个人习惯用Vite来创建Vue3项目。为什么？快，真的快。Vite的开发服务器启动速度，比Webpack快了不是一星半点。你想想看，每次改完代码等热更新，那种煎熬我太懂了。

# 确保你的Node.js版本在16以上
node -v

# 使用Vite创建Vue3项目
npm create vite@latest pinia-course -- --template vue

# 进入项目目录
cd pinia-course

# 安装依赖
npm install
💡 我的小建议： 创建项目时，项目名最好用英文小写加连字符。我之前有个同事用了中文名，结果在CI/CD流水线上各种报错，排查了半天。

项目创建成功后，你会看到这样的目录结构：

pinia-course/
├── node_modules/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   ├── App.vue
│   └── main.js
├── index.html
├── package.json
├── vite.config.js
└── README.md

2.2 安装Pinia依赖——就一行命令的事

接下来安装Pinia。这一步其实很简单，但有个坑我得提醒你。

npm install pinia

嗯，就这一行。但注意了——不要安装 pinia@next。我记得Pinia刚出的时候，很多人习惯性地装了next版本，结果发现和Vue3正式版不兼容。现在Pinia已经稳定了，直接装最新版就行。

⚠️ 避坑指南： 我曾经在项目里同时装了pinia和vuex，结果两个状态管理库互相干扰，调试了一下午才发现。记住：一个项目只用一种状态管理方案。

2.3 在main.js中注册Pinia——核心步骤

安装完依赖，接下来就是在入口文件里注册Pinia。这一步很多人会漏掉，然后发现组件里怎么也拿不到store的数据。

// src/main.js
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const app = createApp(App)
const pinia = createPinia()

app.use(pinia)
app.mount('#app')

这里有个细节：createPinia() 返回的是一个Pinia实例，然后通过 app.use() 注册到Vue应用中。说白了，这一步就是告诉Vue：「嘿，我要用Pinia来管理状态了，你帮我准备好环境」。

🔑 关键点： 注册顺序有讲究吗？我个人习惯在路由注册之前就注册Pinia。因为有些路由守卫里可能会用到store的数据，如果Pinia还没注册好，就会报错。

2.4 项目结构规划——好的结构让代码更清爽

项目结构这件事，其实没有绝对的标准。但根据我多年的经验，一个好的结构应该满足三个原则：易查找、易扩展、易维护。

我推荐的结构是这样的：

src/
├── stores/          # Pinia状态管理
│   ├── modules/     # 按功能拆分的store模块
│   │   ├── user.js
│   │   ├── cart.js
│   │   └── app.js
│   └── index.js     # 统一导出
├── views/           # 页面组件
├── components/      # 公共组件
├── router/          # 路由配置
├── utils/           # 工具函数
├── api/             # API请求
├── assets/          # 静态资源
├── App.vue
└── main.js

为什么要把stores单独拎出来？你想想看，如果项目里有几十个store文件，散落在各个目录里，找起来得多痛苦。集中管理，一目了然。

目录 用途 说明
stores/modules 按业务模块拆分 每个模块一个文件，比如用户、购物车
stores/index.js 统一导出所有store 方便其他文件引用，减少import路径
api 接口请求封装 和store解耦，职责单一
💡 我的经验： 刚开始学Pinia时，我习惯把所有状态都写在一个store里。结果项目到中期，一个store文件上千行，改个变量名都要全局搜索。后来我学乖了——一个功能模块一个store，清爽多了。

2.5 验证环境是否搭建成功

环境搭好了，怎么知道对不对？写个最简单的测试：

// src/stores/counter.js
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0
  }),
  actions: {
    increment() {
      this.count++
    }
  }
})

然后在任意组件里引用：

<template>
  <div>
    <p>计数：{{ counter.count }}</p>
    <button @click="counter.increment()">+1</button>
  </div>
</template>

<script setup>
import { useCounterStore } from '@/stores/counter'

const counter = useCounterStore()
</script>

如果页面能正常显示计数，点击按钮数字能增加，恭喜你——环境搭建成功了！

⚠️ 常见问题： 如果你遇到「Cannot find module pinia」的错误，八成是忘了安装依赖。别笑，我真见过有人跳过安装步骤直接写代码的。

好了，环境搭好了，下一章咱们就开始真正地写Pinia代码了。说实话，环境搭建这一步虽然枯燥，但基础打牢了，后面学起来才顺畅。你想想看，如果连脚手架都跑不起来，还谈什么状态管理？

← 上一章 📖 返回目录 下一章 →