2-6、Vue前端项目启动与依赖问题解决

Monte

2026-09-28 15:41:48 24 次阅读

后端跑起来了，但用户看到的是前端页面。很多公司是前后端分离的，前端用Vue。这节讲前端项目启动和常见依赖问题。

一、安装Node.js

Vue项目需要Node.js环境。

1. 下载

官网：https://nodejs.org/

选择LTS（长期支持版），比如Node.js 18.x或20.x。

注意：别装太新的版本，有些老项目不兼容Node.js 21+。推荐Node.js 18 LTS，兼容性最好。

国内镜像：https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/

2. 安装

双击安装包，一路下一步，注意：

安装路径无中文无空格，如D:\nodejs
勾选"Add to PATH"

3. 验证

Shell

node -v
# 输出：v18.19.0

npm -v
# 输出：10.2.3

4. 配置npm镜像

默认npm从国外下载，速度慢，配国内镜像：

Shell

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
# 输出：https://registry.npmmirror.com

5. 配置npm全局安装路径

不配的话全局包会装到C盘：

Shell

# 创建全局安装目录
mkdir D:\nodejs\npm_global

# 设置全局安装路径
npm config set prefix "D:\nodejs\npm_global"

# 设置缓存路径
npm config set cache "D:\nodejs\npm_cache"

环境变量Path里添加D:\nodejs\npm_global。

6. 安装nvm（可选，推荐）

如果多个项目需要不同Node版本，装nvm管理：

下载nvm-windows：https://github.com/coreybutler/nvm-windows/releases

Shell

# 安装Node.js 18
nvm install 18

# 使用Node.js 18
nvm use 18

# 查看已安装版本
nvm list

二、安装pnpm/yarn（看项目要求）

有些项目不用npm，用pnpm或yarn。

看项目用的哪个

看项目根目录的锁文件：

锁文件	包管理器	安装命令
`package-lock.json`	npm	`npm install`
`pnpm-lock.yaml`	pnpm	`pnpm install`
`yarn.lock`	yarn	`yarn`

安装pnpm

Shell

npm install -g pnpm

安装yarn

Shell

npm install -g yarn

pnpm配镜像

Shell

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

三、启动Vue项目

1. 进入项目目录

Shell

cd D:/projects/company-frontend

2. 安装依赖

Shell

# 用npm
npm install

# 或用pnpm
pnpm install

# 或用yarn
yarn

首次安装可能需要几分钟，取决于项目依赖数量和网络速度。

3. 启动开发服务器

看package.json里的scripts：

JSON

{
  "scripts": {
    "dev": "vite",
    "serve": "vue-cli-service serve",
    "build": "vite build",
    "lint": "eslint ."
  }
}

启动命令一般是：

Shell

# Vue3 + Vite
npm run dev

# Vue2 + Vue CLI
npm run serve

4. 访问页面

控制台会输出访问地址：

TEXT

  VITE v4.5.0  ready in 567 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.100:5173/

浏览器打开http://localhost:5173/就能看到页面了。

5. IDEA里启动前端

IDEA也能打开前端项目：

File → Open → 选择前端项目目录
打开IDEA底部Terminal
执行npm install和npm run dev

IDEA对Vue有语法支持（装Vue插件），但前端开发还是推荐用VS Code。

四、前端配置修改

1. 修改后端API地址

前端项目要配置后端接口地址，让它知道请求发给谁。

Vite项目 —— 找.env或.env.development文件：

TEXT

VITE_API_BASE_URL=http://localhost:8080/api

Vue CLI项目 —— 找vue.config.js或.env.development：

JavaScript

// vue.config.js
module.exports = {
  devServer: {
    port: 8081,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        pathRewrite: { '^/api': '' }
      }
    }
  }
}

或者在代码里配置 —— 找src/utils/request.js或src/api/index.js：

JavaScript

const baseURL = 'http://localhost:8080/api'
// 或
const baseURL = '/api'  // 配合proxy使用

2. 修改端口

前端默认端口可能被占用，改一下：

Vite —— vite.config.js：

JavaScript

export default defineConfig({
  server: {
    port: 3000,  // 改成你想要的端口
    host: '0.0.0.0'  // 允许局域网访问
  }
})

Vue CLI —— vue.config.js：

JavaScript

module.exports = {
  devServer: {
    port: 3000
  }
}

3. 关闭ESLint校验（临时）

有些项目ESLint很严格，保存就报一堆警告。开发时可以临时关掉：

JavaScript

// vite.config.js
export default defineConfig({
  eslint: {
    overrideConfigFile: false
  }
})

或者修改package.json：

JSON

{
  "eslintConfig": {
    "rules": {
      "no-unused-vars": "off",
      "no-console": "off"
    }
  }
}

五、常见依赖问题

问题1：npm install 很慢或失败

原因： 网络问题，npm从国外下载。

解决：

Shell

# 确认镜像配置
npm config get registry

# 如果不是淘宝镜像，设置一下
npm config set registry https://registry.npmmirror.com

# 重新安装
rm -rf node_modules
npm install

问题2：node-sass安装失败

TEXT

gyp ERR! find Python
gyp ERR! node-gyp -v

node-sass是个编译型依赖，对Node版本和Python有要求，经常装不上。

解决：

方法1：换dart-sass（纯JS实现，不编译）

Shell

npm uninstall node-sass
npm install sass

方法2：指定node-sass镜像

Shell

npm config set sass_binary_site=https://npmmirror.com/mirrors/node-sass
npm install node-sass

问题3：node版本不兼容

TEXT

error:0308010C:digital envelope routines::unsupported

Node.js 17+和旧版webpack不兼容。

解决：

方法1：降级Node.js到16

Shell

nvm install 16
nvm use 16

方法2：设置环境变量

Shell

# Windows
set NODE_OPTIONS=--openssl-legacy-provider
npm run dev

# 或在package.json里修改scripts
"dev": "set NODE_OPTIONS=--openssl-legacy-provider && vite"

问题4：依赖版本冲突

TEXT

npm ERR! ERESOLVE unable to resolve dependency tree

解决：

Shell

# 方法1：用legacy-peer-deps忽略冲突
npm install --legacy-peer-deps

# 方法2：用force强制安装
npm install --force

# 方法3：删掉lock文件重新安装
rm package-lock.json
rm -rf node_modules
npm install

问题5：找不到模块

Error: Cannot find module 'xxx'

某个依赖没装上。

Shell

# 单独安装这个模块
npm install xxx

# 或重新安装所有依赖
rm -rf node_modules
rm package-lock.json
npm install

问题6：端口被占用

TEXT

Port 5173 is already in use

解决：

方法1：改端口（上面讲过）

方法2：杀掉占用进程

Shell

# 查看占用
netstat -ano | findstr 5173

# 杀掉
taskkill /PID 进程ID /F

问题7：pnpm install报错找不到workspace

有些项目用了pnpm workspace，但你在子目录里执行了install。

解决： 在项目根目录执行pnpm install。

六、前端构建

开发时用npm run dev启动开发服务器，但要部署时需要构建：

Shell

# 构建生产包
npm run build

构建产物在dist/目录下。

Shell

# 本地预览构建结果
npm run preview

构建常见问题

问题：构建报错 "Maximum call stack size exceeded"

可能是循环依赖。检查最近的代码改动。

问题：构建后页面空白

可能是路径问题。vite.config.js里加：

JavaScript

export default defineConfig({
  base: './'  // 相对路径
})

七、常见Vue项目结构

TEXT

frontend/
  public/             (静态资源)
  src/
    api/              (接口请求)
    assets/           (图片、样式)
    components/       (公共组件)
    views/ 或 pages/  (页面)
    router/           (路由)
    store/            (Vuex/Pinia状态管理)
    utils/            (工具函数)
    App.vue           (根组件)
    main.js           (入口文件)
  .env                (环境变量)
  .env.development    (开发环境变量)
  vite.config.js      (Vite配置)
  package.json        (依赖和脚本)

入口文件 main.js

JavaScript

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { createPinia } from 'pinia'

const app = createApp(App)
app.use(router)
app.use(createPinia())
app.mount('#app')

小结

步骤	关键点
安装Node.js	用LTS版本，配淘宝镜像
安装依赖	看锁文件确定用npm/pnpm/yarn
配置API地址	改.env或vue.config.js
启动	npm run dev 或 npm run serve
依赖报错	删node_modules重装

前端也跑起来了，下一步前后端联调。