或者用pnpm

terry 1小时前阅读数 29 #Vue

文章标签 pnpm 包管理器

Vue3怎么安装？有哪些适合新手的安装方式和避坑点？

最近打算换个前端框架做个轻量级的小项目？或者是刚毕业的前端新人，准备赶赶Vue3的热度？不管是哪种情况，首先绕不开的肯定是“把Vue3装到自己电脑上”这一步，别小看安装这件事，选对了方式能少踩好多坑，用起来也顺手；要是随便试了个过时的方法，可能连最基本的Hello World都跑不起来，今天咱们就掰开揉碎了说，从环境准备到每个安装方式的步骤、优缺点，再到新手高频踩的雷,一个都不落下。

先唠唠Vue3安装前必须搭的环境

不管你是用官方脚手架还是CDN直接用，有两个东西是基础中的基础——Node.js和npm/yarn/pnpm这些包管理器，很多新手第一次装Vue3卡壳，90%都是Node.js的版本不对或者没装好。

Node.js版本怎么选？

现在打开Node.js的官网，能看到两个大按钮：一个标着LTS，另一个标着Current，很多朋友会问“LTS和Current有啥区别？选哪个？”其实很简单，LTS是长期支持版，大概会维护两年半左右，稳定性最高，不管是做项目还是学习，新手直接选LTS版绝对不会错；Current是尝鲜版，更新很快，会有最新的功能，但可能会有小bug,适合技术大佬用来做实验或者赶新特性。

那具体选LTS的哪个小版本呢？查过Vue3的官方文档要求，Node.js的版本至少要是0.0及以上，要是低于18，很多新的Vue3工具链（比如Vite4+、Vue CLI 5最新版）都没法正常运行，我自己现在用的是20.x的LTS,跑各种Vue3项目都没问题。

怎么检查自己有没有装过Node.js？

要是你不确定电脑上有没有Node.js，直接打开终端就行——Windows用户按Win+R，输入cmd回车；Mac用户按Command+空格，输入Terminal回车；Linux用户就不用我多说啦，直接打开终端,然后分别输入两个命令：

node -v
npm -v

要是弹出一串数字（比如v20.12.2和10.5.0），就说明已经装好了；要是提示“找不到命令”或者类似的内容,那就得去官网下载安装包啦。

要不要把npm换成pnpm/yarn？

新手刚接触的话，先用自带的npm也没问题，但要是之后做稍微大一点的项目，或者想下载依赖更快、占用空间更小，那强烈建议换成pnpm，pnpm有个硬链接的特性，相同的依赖只会在电脑上存一份，不像npm那样每个项目都单独复制一份，能省不少硬盘空间；下载速度也比npm快很多，尤其是在中国，因为pnpm默认就支持淘宝镜像吗？不对，默认还是官方源,但换源和npm一样简单。

安装pnpm也很方便,终端里直接输入：

npm install -g pnpm

就行，安装完输入pnpm -v检查一下版本，要是你习惯用yarn，也可以继续用，但yarn现在分为Yarn Classic（1.x）和Yarn Berry（2.x+）两个大版本，新手要是想用yarn，建议选Classic 1.x，教程多,遇到问题好解决。

Vue3的三种主流安装方式，新手选哪种？

环境搭好之后，就可以正式装Vue3啦，现在主流的安装方式有三种：CDN引入、官方脚手架Vue CLI创建项目、新一代构建工具Vite创建项目，这三种方式各有各的适用场景,咱们一个一个说。

第一种：CDN引入——适合临时测试、不想装环境的朋友

CDN引入应该是最简单的方式了，连环境准备都可以省一半（至少不用专门为了测试装Node.js），直接在HTML文件里加个script标签就行,这种方式特别适合：

刚接触Vue，想先写个Hello World看看效果；
做个非常小的单页，比如倒计时、简单的表单验证；
在现有的项目（比如老的jQuery项目）里嵌入一小部分Vue3的功能。

CDN引入有两种模式：开发模式和生产模式，开发模式会有完整的警告信息，方便调试；生产模式会被压缩过，体积更小，加载更快，但没有警告，所以新手刚开始一定要用开发模式。

具体怎么操作呢？新建一个index.html文件,然后把下面的代码复制进去就行：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">Vue3 CDN测试</title>
  <!-- 开发模式，包含完整的警告 -->
  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <!-- 生产模式，压缩后体积小，没警告 -->
  <!-- <script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script> -->
</head>
<body>
  <!-- Vue的挂载点 -->
  <div id="app">
    <h1>{{ message }}</h1>
    <button @click="count++">点击次数: {{ count }}</button>
  </div>
  <script>
    // 创建Vue应用实例
    const { createApp, ref } = Vue;
    createApp({
      setup() {
        // 定义响应式数据
        const message = ref('你好，Vue3！');
        const count = ref(0);
        // 返回给模板使用
        return {
          message,
          count
        };
      }
    }).mount('#app'); // 把应用挂载到id为app的div上
  </script>
</body>
</html>

写好之后，直接双击打开index.html文件，就能看到效果啦——页面上会显示“你好，Vue3！”和一个点击计数的按钮，点一下按钮数字就会加1,是不是很简单？

不过CDN引入也有缺点，比如没法用单文件组件（.vue文件），没法用TypeScript，没法用Vue Router、Pinia这些官方生态库的最佳实践（虽然也能用，但配置起来比较麻烦），所以只适合临时测试，要是做完整的项目,还是得用脚手架或者Vite。

第二种：Vue CLI创建项目——适合习惯旧工具链、需要兼容性的朋友

Vue CLI是Vue官方最早推出的脚手架工具，之前Vue2的时候用的人特别多，现在Vue3也支持，Vue CLI的优点是：

教程非常多，不管是中文还是英文,遇到问题一搜就能找到解决方案；
内置了很多插件，比如Vue Router、Pinia、TypeScript、ESLint、Prettier这些，安装的时候直接勾选就行,不用自己手动配置；
兼容性很好，支持很多旧的浏览器（比如IE11），如果你的项目需要兼容旧浏览器，那Vue CLI是个不错的选择。

不过Vue CLI的缺点也很明显：

基于Webpack构建，冷启动和热更新的速度比较慢，尤其是项目稍微大一点之后，冷启动可能要等几十秒甚至一分钟，热更新也要等几秒,开发体验不太好；
配置比较繁琐，虽然内置了很多插件，但如果需要自定义配置，得自己写vue.config.js文件,对新手不太友好；
官方现在已经把重心转移到Vite上了，Vue CLI的更新速度会变慢,未来可能不会有大的功能更新了。

那怎么用Vue CLI创建Vue3项目呢？首先得全局安装Vue CLI：

npm install -g @vue/clipnpm add -g @vue/cli
# 或者用yarn
yarn global add @vue/cli

安装完之后，输入vue -V（注意是大写的V）检查一下版本，要是版本低于5.0.0，建议升级一下，因为只有5.x的版本才完全支持Vue3。

升级Vue CLI的话，直接重新运行安装命令就行，npm/yarn/pnpm会自动覆盖旧版本。

然后找一个你想存项目的文件夹，打开终端,输入创建项目的命令：

vue create my-vue3-cli-project

这里的my-vue3-cli-project是项目名，你可以随便起，但不能有大写字母、空格、中文这些特殊字符，只能用小写字母、数字、下划线和短横线。

输入命令之后，会进入一个交互式的选择界面，新手第一次的话，建议选“Default (Vue 3)”，直接回车就行；要是你想自己选插件，就选“Manually select features”，然后用上下箭头移动，空格勾选，回车确认,常用的插件有：

Babel：把ES6+的代码转换成ES5,兼容旧浏览器；
TypeScript：类型安全,适合做大型项目；
Router：Vue官方的路由库,用来做单页应用的页面跳转；
Vuex/Pinia：状态管理库，Vuex是旧版的，Pinia是新版的,新手直接选Pinia就行；
CSS Pre-processors：CSS预处理器，比如Sass/Less/Stylus,新手选Less或者Sass都可以；
Linter / Formatter：代码检查和格式化工具，新手刚开始可以先不选,等熟悉了之后再加上；
Unit Testing：单元测试,新手刚开始也可以先不选；
E2E Testing：端到端测试,新手刚开始也可以先不选。

选好插件之后，会让你选Vue的版本，直接选3.x就行；然后会让你选路由模式，有Hash模式和History模式，新手先选Hash模式吧，History模式需要后端配合配置服务器，不然刷新页面会404；接下来会让你选CSS预处理器，刚才选了的话这里选一个就行；然后会让你选把配置文件放在单独的文件里还是package.json里，新手选单独的文件吧，看起来更清楚；最后会问你要不要保存这次的配置作为预设，下次创建项目的时候直接用,新手也可以先不保存。

所有选择都做完之后，Vue CLI就会自动下载依赖、创建项目文件，等个几分钟（取决于你的网络速度），项目就创建好了，创建好之后，终端会提示你进入项目文件夹,然后运行启动命令：

cd my-vue3-cli-project
npm run servepnpm serve
# 或者用yarn
yarn serve

等终端显示“App running at: - Local: http://localhost:8080/”之后，打开浏览器，输入http://localhost:8080/，就能看到Vue CLI的默认页面啦。

第三种：Vite创建项目——官方推荐，速度最快，新手必选

Vite是尤雨溪（Vue的创始人）在2020年推出的新一代构建工具，专门为现代前端开发设计的，现在已经成为Vue3的官方推荐构建工具了,Vite的优点非常多：

速度极快，不管是冷启动还是热更新，都比Webpack快很多——冷启动几乎是秒开，热更新也是毫秒级的，哪怕项目很大，速度也不会变慢太多,开发体验非常好；
配置非常简单，默认就支持单文件组件、TypeScript、Vue Router、Pinia这些，很多配置都是开箱即用的,不用自己手动写太多配置文件；
基于ES Modules，支持热模块替换（HMR），只会更新你修改的那个组件,不会重新编译整个项目；
生态越来越完善，现在已经支持很多插件了，比如Sass/Less/Stylus、ESLint、Prettier、单元测试、端到端测试这些,常用的功能都有；
官方持续维护，更新速度很快,会有很多新功能。

可以说，现在做Vue3项目，不管是新手还是老手，首选都是Vite,那怎么用Vite创建Vue3项目呢？

不用全局安装Vite，直接用npm create vite@latest命令就行，这个命令会临时下载最新版的Vite，创建完项目之后就会删除,不会占用你的全局空间：

npm create vite@latest my-vue3-vite-project
# 或者用pnpm（推荐，速度更快）
pnpm create vite@latest my-vue3-vite-project
# 或者用yarn
yarn create vite my-vue3-vite-project

这里的my-vue3-vite-project同样是项目名，命名规则和Vue CLI一样。

输入命令之后，也会进入一个交互式的选择界面，但比Vue CLI简单很多：

首先会让你确认项目名，要是刚才输入了,直接回车就行；
然后会让你选框架,这里直接选Vue就行；
最后会让你选变体，有JavaScript、TypeScript、JavaScript + Customize with create-vue、TypeScript + Customize with create-vue这四个选项，新手刚开始可以先选JavaScript；要是你想直接加上Vue Router、Pinia、ESLint、Prettier这些插件，就选JavaScript + Customize with create-vue或者TypeScript + Customize with create-vue（推荐TypeScript，对新手之后的成长有帮助）。

选好之后，Vite就会自动创建项目文件，注意哦，Vite不会自动下载依赖，创建完之后会提示你手动进入项目文件夹、安装依赖、启动项目：

cd my-vue3-vite-project
# 安装依赖
npm install
# 或者用pnpm（推荐）
pnpm install
# 或者用yarn
yarn install
# 启动开发服务器
npm run devpnpm dev
# 或者用yarn
yarn dev

等终端显示“Local: http://localhost:5173/”之后，打开浏览器，输入http://localhost:5173/，就能看到Vite的默认页面啦——页面上有个Vue的logo，还有计数器、导入组件这些功能，比Vue CLI的默认页面更实用。

要是刚才选了Customize with create-vue的选项,安装依赖之后还会有几个选择：

要不要启用TypeScript？刚才选了的话这里直接选Yes；
要不要启用JSX？新手刚开始可以先选No；
要不要添加Vue Router？做单页应用的话选Yes；
要不要添加Pinia？做有状态管理需求的项目选Yes；
要不要添加Vitest？单元测试,新手刚开始可以先选No；
要不要添加Cypress或者Playwright？端到端测试,新手刚开始也可以先选No；
要不要添加ESLint？代码检查，新手刚开始可以先选No,等熟悉了之后再加上；
要不要添加Prettier？代码格式化，新手刚开始也可以先选No,等熟悉了之后再加上。

所有选择都做完之后,再运行启动命令就行。

新手安装Vue3高频踩的5个坑，千万别踩！

刚才说了三种安装方式，现在再说说新手安装Vue3的时候最常踩的5个坑，要是能避开这些坑,安装过程会顺利很多。

坑1：Node.js版本太低

刚才也提到过，Vue3的官方文档要求Node.js至少要是18.0.0及以上，要是低于18，很多工具链都没法正常运行，比如用Vite创建项目的时候，可能会提示“Vite requires Node.js version 18.0.0 or higher”；用Vue CLI 5最新版创建项目的时候,也可能会有类似的提示。

解决方法：去Node.js官网下载最新的LTS版（18.x或20.x），重新安装就行，重新安装之前，建议先把旧版本的Node.js卸载掉,避免版本冲突。

坑2：包管理器下载依赖太慢，甚至下载失败

这个问题在中国特别常见，因为npm/yarn/pnpm的默认源都是国外的，国内访问速度很慢,甚至会被墙。

解决方法：把包管理器的源换成国内的镜像源,比如淘宝镜像源。

npm换源：

npm config set registry https://registry.npmmirror.com

pnpm换源：

pnpm config set registry https://registry.npmmirror.com

yarn换源：
```
yarn config set registry https://registry.npmmirror.com
```
换源之后，输入npm config get registry（或者对应的pnpm/yarn命令）检查一下，要是显示刚才设置的淘宝镜像源，就说明换成功了，换源之后，下载依赖的速度会快很多,也不容易下载失败。

坑3：用Vue CLI创建项目的时候选了Vue2的版本

很多新手第一次用Vue CLI创建项目的时候，没注意看交互式选择界面的内容，直接选了默认的“Default (Vue 2)”，结果创建出来的是Vue2的项目,不是Vue3的。

解决方法：创建项目的时候，一定要仔细看交互式选择界面的内容，要么直接选“Default (Vue 3)”，要么选“Manually select features”之后再选3.x的版本，要是已经创建成Vue2的项目了，没关系，直接删除项目文件夹,重新创建就行。

坑4：用Vite创建项目之后忘了安装依赖

刚才也提到过，Vite不会像Vue CLI那样自动下载依赖，创建完项目之后必须手动进入项目文件夹、安装依赖，不然启动开发服务器的时候会提示“找不到模块”或者类似的内容。

解决方法：严格按照终端的提示操作，创建完项目之后先cd进入项目文件夹，然后安装依赖,最后再启动开发服务器。

坑5：启动开发服务器之后，在浏览器里输入的地址不对

很多新手启动开发服务器之后，会随便输入一个地址，比如http://localhost:8080/，但其实Vite的默认端口是5173，不是8080（8080是Vue CLI的默认端口）；而且有时候端口被占用了，Vite会自动换一个端口，比如5174、5175之类的。

解决方法：启动开发服务器之后，一定要看终端显示的“Local:”后面的地址，直接复制那个地址到浏览器里打开就行，要是你想固定Vite的端口，可以在项目根目录下的vite.config.js（或者vite.config.ts）文件里加一个server.port配置：

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
  plugins: [vue()],
  server: {
    port: 3000 // 固定端口为3000
  }
})