4. 开发环境搭建：Node.js与npm安装、Vue3项目初始化、项目目录结构设计、ESLint与Prettier配置

好，咱们正式开始动手了。这一章我带你搭好开发环境。说白了，就是给大屏组件库盖个地基。地基稳不稳，直接决定后面盖楼的速度和质量。

我个人习惯，每开始一个新项目，都会花半小时把环境理清楚。别小看这一步，我在项目中遇到过好几次因为环境不一致导致的诡异bug——本地跑得好好的，同事一拉代码就报错。嗯，后来我们都学乖了。

4.1 Node.js 与 npm 安装

Vue3 项目依赖 Node.js 环境。Node.js 自带了 npm（包管理器），所以我们只需要装一个。

第一步：下载 Node.js

去官网 https://nodejs.org，下载 LTS 版本。LTS 是长期支持版，稳定，适合生产环境。别追最新版，容易踩坑。

第二步：安装

Windows 用户一路 Next 就行。Mac 用户建议用 Homebrew：

brew install node

第三步：验证安装

打开终端，输入：

node -v
npm -v

看到版本号就说明装好了。我一般会看到类似这样的输出：

v18.17.0
9.6.7
小提示： 如果你之前装过旧版本，建议先卸载干净。我曾经因为残留的旧版本导致全局包冲突，排查了半天。

4.2 Vue3 项目初始化

环境装好了，咱们用 Vite 来创建项目。Vite 是 Vue 官方推荐的构建工具，比 Webpack 快很多。你想想看，以前用 Webpack 启动项目要等十几秒，Vite 几乎是秒开。

在终端里执行：

npm create vite@latest my-dashboard-components -- --template vue

这里 my-dashboard-components 是项目名，你可以改成自己的。后面 --template vue 指定了使用 Vue 模板。

创建完成后，进入项目目录并安装依赖：

cd my-dashboard-components
npm install

然后启动开发服务器：

npm run dev

浏览器打开 http://localhost:5173，看到 Vue 的欢迎页面就成功了。

注意： 如果你用的是 npm 7 以上版本，可能会自动安装 peer dependencies。这有时候会带来版本冲突。我建议用 npm install --legacy-peer-deps 来避免。

4.3 项目目录结构设计

项目初始化好了，但默认的目录结构不适合做大屏组件库。我们需要重新规划。我个人习惯这样组织：

my-dashboard-components/
├── src/
│   ├── components/        # 组件源码
│   │   ├── charts/        # 图表组件
│   │   ├── widgets/       # 小部件组件
│   │   └── layouts/       # 布局组件
│   ├── composables/       # 组合式 API 逻辑
│   ├── assets/            # 静态资源
│   ├── styles/            # 全局样式
│   ├── utils/             # 工具函数
│   └── App.vue
├── public/
├── docs/                  # 组件文档
├── examples/              # 使用示例
├── package.json
└── vite.config.js

为什么这么分？

  • components/charts/：放折线图、柱状图、饼图等图表组件。每个组件一个文件夹，方便维护。
  • components/widgets/：放数字滚动、进度条、状态指示灯等小部件。
  • components/layouts/：放栅格系统、容器组件等布局相关。
  • composables/：Vue3 的组合式 API 逻辑，比如数据请求、响应式状态管理。
  • docs/：组件使用文档，我习惯用 Markdown 写，后面可以生成静态站点。
核心原则： 按功能模块划分，而不是按文件类型。这样每个组件都是自包含的，方便复用和测试。

4.4 ESLint 与 Prettier 配置

代码规范是团队协作的基石。我见过太多因为代码风格不统一导致的代码审查争吵。所以，从一开始就配好 ESLint 和 Prettier。

安装依赖：

npm install -D eslint prettier eslint-plugin-vue eslint-config-prettier

配置 ESLint：

在项目根目录创建 .eslintrc.cjs：

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    'prettier'
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module'
  },
  rules: {
    'vue/multi-word-component-names': 'off',
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
  }
}

配置 Prettier：

创建 .prettierrc：

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

我个人习惯不加分号，用单引号。你如果喜欢加分号，把 semi 改成 true 就行。

配置 VS Code：

在 .vscode/settings.json 里加上：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

这样每次保存文件，都会自动格式化并修复 ESLint 问题。

避坑指南： 我曾经在团队里遇到过 ESLint 和 Prettier 规则冲突的情况。比如 ESLint 要求缩进 2 空格，Prettier 却设成了 4 空格。解决办法就是安装 eslint-config-prettier，它会关闭所有与 Prettier 冲突的 ESLint 规则。

4.5 验证配置

配置好了，我们来验证一下。在 src 目录下随便写点代码：

// src/test.js
const name = 'hello'
console.log(name)

然后运行：

npx eslint src/test.js

如果没有报错，说明 ESLint 配置生效了。再试试 Prettier：

npx prettier --check src/test.js

如果格式不对，它会提示你。运行 npx prettier --write src/test.js 可以自动修复。

小技巧： 我习惯在 package.json 的 scripts 里加上 lint 命令："lint": "eslint src --ext .js,.vue"。这样团队里每个人都能一键检查代码规范。

好了，环境搭建就到这里。下一章我们开始写第一个大屏组件——一个带数据驱动的数字滚动器。到时候你会看到，今天搭的这些配置会帮你省下多少时间。

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