Vue CLI（三）vue.config.js 配置文件详解

原创 已于 2025-10-12 12:12:20 修改 · 1.1k 阅读 · 25 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#javascript #vue.js #前端 #VUE CLI #vue.config.js

于 2025-10-11 19:30:31 首次发布

vue.config.js 常用参数详解

1. 基本结构

// vue.config.js
module.exports = {
  // 这里填写各种配置项
}

2. 详细参数列表及说明

2.1 publicPath

  • 作用：指定应用的部署路径（资源的基础路径）。
  • 默认：'/'
  • 常用场景：部署到子目录时需设置。
publicPath: process.env.NODE_ENV === 'production' ? '/sub-path/' : '/'

2.2 outputDir

  • 作用：指定打包输出目录。
  • 默认：'dist'
outputDir: 'dist'

2.3 assetsDir

  • 作用：静态资源（js、css、img、fonts）存放目录，相对于 outputDir。
  • 默认：''
assetsDir: 'static'

2.4 indexPath

  • 作用：指定生成的 index.html 的输出路径（相对于 outputDir）。
  • 默认：'index.html'
indexPath: 'index.html'

2.5 filenameHashing

  • 作用：是否在生成的静态资源文件名添加 hash，防止缓存。
  • 默认：true
filenameHashing: true

2.6 pages

  • 作用：多页面配置。
  • 类型：对象
pages: {
  index: {
    entry: 'src/main.js',
    template: 'public/index.html',
    filename: 'index.html',
    title: '首页',
    chunks: ['chunk-vendors', 'chunk-common', 'index']
  },
  // 其他页面...
}

2.7 lintOnSave

  • 作用：保存时是否进行代码校验（ESLint）。
  • 默认：true
  • 可选值：true、false、'error'
lintOnSave: false

2.8 runtimeCompiler

  • 作用：是否使用包含编译器的 Vue 构建版本（允许在运行时编译模板）。
  • 默认：false
runtimeCompiler: true

2.9 transpileDependencies

  • 作用：需要通过 Babel 显式转译的第三方依赖。
  • 类型：数组
transpileDependencies: ['some-es6-package']

2.10 productionSourceMap

  • 作用：生产环境是否生成 source map。
  • 默认：true
productionSourceMap: false

2.11 crossorigin

  • 作用：设置 <link rel="stylesheet"> 和 <script> 标签的 crossorigin 属性。
  • 可选值：'anonymous'、'use-credentials'、false
crossorigin: 'anonymous'

2.12 integrity

  • 作用：是否为构建的资源启用 Subresource Integrity（SRI）。
  • 默认：false
integrity: true

2.13 configureWebpack

  • 作用：直接修改 webpack 配置（对象或函数）。
  • 类型：对象或函数
configureWebpack: {
  plugins: [
    // 自定义插件
  ]
}

或者：

configureWebpack: config => {
  config.plugins.push(/* 插件 */)
}

2.14 chainWebpack

  • 作用：使用 webpack-chain 细粒度修改 webpack 配置。
chainWebpack: config => {
  config.module
    .rule('svg')
    .test(/\.svg$/)
    .use('svg-loader')
    .loader('svg-loader')
}

2.15 css 相关配置

css: {
  // 是否提取 CSS 到单独文件
  extract: true,
  // 是否开启 CSS source map
  sourceMap: false,
  // CSS loader 配置
  loaderOptions: {
    css: {},
    less: {},
    sass: {},
    scss: {},
    stylus: {},
    postcss: {}
  },
  // 是否启用 CSS modules
  requireModuleExtension: false
}

2.16 devServer 开发服务器配置

devServer: {
  open: true, // 自动打开浏览器
  host: '0.0.0.0', // 允许外部访问
  port: 8080, // 端口
  https: false, // 是否启用 https
  hotOnly: false, // 热更新
  proxy: { // 代理配置
    '/api': {
      target: 'http://localhost:3000',
      changeOrigin: true,
      pathRewrite: { '^/api': '' }
    }
  }
}

2.17 pluginOptions

  • 作用：第三方插件的自定义配置。
pluginOptions: {
  'style-resources-loader': {
    preProcessor: 'scss',
    patterns: []
  }
}

3. 其他参数

  • pwa：PWA 支持配置
  • parallel：是否使用多线程压缩
  • devtool：自定义 source map 生成方式

4. 完整示例

module.exports = {
  publicPath: '/',
  outputDir: 'dist',
  assetsDir: 'static',
  indexPath: 'index.html',
  filenameHashing: true,
  lintOnSave: false,
  runtimeCompiler: false,
  transpileDependencies: [],
  productionSourceMap: false,
  crossorigin: undefined,
  integrity: false,
  configureWebpack: {},
  chainWebpack: config => {},
  css: {
    extract: true,
    sourceMap: false,
    loaderOptions: {},
    requireModuleExtension: false
  },
  devServer: {
    open: true,
    host: 'localhost',
    port: 8080,
    https: false,
    hotOnly: false,
    proxy: {},
  },
  pluginOptions: {}
}

参考文档

总结

  • vue.config.js 是 Vue CLI 项目的总配置文件，参数丰富，可高度定制项目行为。
  • 常用参数如 publicPath、outputDir、devServer、css 等。
  • webpack 相关配置推荐用 configureWebpack 和 chainWebpack。
  • 多页面开发用 pages。
  • 开发服务器、代理用 devServer。

5. 进阶参数与用法

5.1 pwa

  • 作用：配置 PWA（渐进式网页应用）相关参数，需要安装 @vue/cli-plugin-pwa。
  • 常用配置：
pwa: {
  name: '我的应用',
  themeColor: '#4DBA87',
  msTileColor: '#000000',
  appleMobileWebAppCapable: 'yes',
  appleMobileWebAppStatusBarStyle: 'black',
  manifestOptions: {
    background_color: '#42b983'
  }
}

5.2 parallel

  • 作用：是否使用多进程处理 Babel 或 TypeScript 以加快构建速度。
  • 默认：根据系统 CPU 核数自动决定。
parallel: true

5.3 devtool

  • 作用：自定义 source map 生成方式（覆盖默认 source map 配置）。
  • 常用值：source-map、cheap-module-source-map、eval-source-map 等。
configureWebpack: {
  devtool: 'source-map'
}

5.4 crossorigin/integrity

  • 作用：安全相关，通常用于 CDN 部署。
crossorigin: 'anonymous',
integrity: true

5.5 loaderOptions（css）

  • 作用：为各类 CSS 预处理器传递参数。
css: {
  loaderOptions: {
    less: {
      modifyVars: {
        'primary-color': '#42b983'
      },
      javascriptEnabled: true
    },
    sass: {
      additionalData: `@import "@/styles/variables.scss";`
    }
  }
}

6. 高级配置技巧

6.1 环境变量与配置

  • 你可以在项目根目录下创建 .env 文件（如 .env.development, .env.production），并在 vue.config.js 中读取环境变量：
publicPath: process.env.VUE_APP_PUBLIC_PATH
  • 在代码中通过 process.env.VUE_APP_XXX 访问自定义环境变量。

6.2 配置 SVG 图标自动导入

chainWebpack: config => {
  const svgRule = config.module.rule('svg')
  svgRule.uses.clear()
  svgRule
    .use('svg-sprite-loader')
    .loader('svg-sprite-loader')
    .options({ symbolId: 'icon-[name]' })
}

6.3 配置全局样式/变量

css: {
  loaderOptions: {
    scss: {
      additionalData: `@import "@/styles/global.scss";`
    }
  }
}

6.4 配置代理（解决跨域）

devServer: {
  proxy: {
    '/api': {
      target: 'http://backend.server',
      changeOrigin: true,
      pathRewrite: { '^/api': '' }
    }
  }
}

6.5 配置多页面应用

pages: {
  index: {
    entry: 'src/main.js',
    template: 'public/index.html',
    filename: 'index.html'
  },
  admin: {
    entry: 'src/admin/main.js',
    template: 'public/admin.html',
    filename: 'admin.html'
  }
}

7. 常见问题与解决方案

7.1 webpack 配置冲突

  • 使用 configureWebpack 适合简单合并，chainWebpack 适合复杂定制。

7.2 代理失效

  • 检查 devServer.proxy 配置，端口、路径是否正确，changeOrigin 是否为 true。

7.3 CSS 全局变量失效

  • 确认 loaderOptions 的写法是否正确，路径是否有效。

7.4 构建速度慢

  • 关闭 productionSourceMap
  • 启用 parallel
  • 精简依赖，合理配置 transpileDependencies

8. vue.config.js 完整示例（进阶）

module.exports = {
  publicPath: process.env.NODE_ENV === 'production' ? '/sub-path/' : '/',
  outputDir: 'dist',
  assetsDir: 'static',
  indexPath: 'index.html',
  filenameHashing: true,
  lintOnSave: process.env.NODE_ENV !== 'production',
  runtimeCompiler: true,
  transpileDependencies: ['vue-echarts', 'resize-detector'],
  productionSourceMap: false,
  crossorigin: 'anonymous',
  integrity: true,
  configureWebpack: {
    devtool: 'source-map',
    plugins: [
      // 你的自定义插件
    ]
  },
  chainWebpack: config => {
    config.module
      .rule('svg')
      .test(/\.svg$/)
      .use('svg-sprite-loader')
      .loader('svg-sprite-loader')
      .options({ symbolId: 'icon-[name]' })
  },
  css: {
    extract: true,
    sourceMap: false,
    loaderOptions: {
      scss: {
        additionalData: `@import "@/styles/global.scss";`
      }
    },
    requireModuleExtension: false
  },
  devServer: {
    open: true,
    host: 'localhost',
    port: 8080,
    https: false,
    hotOnly: false,
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        pathRewrite: { '^/api': '' }
      }
    }
  },
  pluginOptions: {
    'style-resources-loader': {
      preProcessor: 'scss',
      patterns: [path.resolve(__dirname, 'src/styles/variables.scss')]
    }
  },
  pwa: {
    name: '我的PWA应用',
    themeColor: '#42b983',
    manifestOptions: {
      background_color: '#42b983'
    }
  },
  parallel: true
}

10. 高级实用技巧

10.1 自定义环境变量的应用

你可以在 .env 文件中定义变量（如 .env.production）：

VUE_APP_API_BASE=https://api.example.com

在 vue.config.js 和项目代码中都可以通过 process.env.VUE_APP_API_BASE 访问。

10.2 构建体积优化

  • 只打包需要的 locale（以 moment.js 为例）：
configureWebpack: {
  plugins: [
    new webpack.IgnorePlugin({
      resourceRegExp: /^\.\/locale$/,
      contextRegExp: /moment$/
    })
  ]
}
  • 开启 gzip 压缩（需安装 compression-webpack-plugin）：
const CompressionWebpackPlugin = require('compression-webpack-plugin');

configureWebpack: config => {
  if (process.env.NODE_ENV === 'production') {
    config.plugins.push(
      new CompressionWebpackPlugin({
        algorithm: 'gzip',
        test: /\.(js|css|html|svg)$/,
        threshold: 10240,
        minRatio: 0.8
      })
    );
  }
}

10.3 多语言（i18n）集成

如果用 vue-i18n，可通过 pluginOptions 配置：

pluginOptions: {
  i18n: {
    locale: 'zh',
    fallbackLocale: 'en',
    localeDir: 'locales',
    enableInSFC: true
  }
}

10.4 配置别名 alias

方便你在项目中用 @ 或自定义别名引用路径：

const path = require('path');

configureWebpack: {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components')
    }
  }
}

10.5 打包分析

定位包体积问题，推荐集成 webpack-bundle-analyzer：

const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

configureWebpack: config => {
  if (process.env.NODE_ENV === 'production') {
    config.plugins.push(new BundleAnalyzerPlugin());
  }
}

11. 常见场景实战配置

11.1 配置全局 SASS/LESS 变量

css: {
  loaderOptions: {
    scss: {
      additionalData: `@import "~@/styles/variables.scss";`
    }
  }
}

11.2 CDN 引入第三方库

减小打包体积，将常用库通过 CDN 引入：

configureWebpack: {
  externals: {
    vue: 'Vue',
    'vue-router': 'VueRouter',
    axios: 'axios'
  }
},
chainWebpack: config => {
  config.plugin('html').tap(args => {
    args[0].cdn = {
      css: [],
      js: [
        'https://cdn.jsdelivr.net/npm/vue@2/dist/vue.min.js',
        'https://cdn.jsdelivr.net/npm/vue-router@3/dist/vue-router.min.js',
        'https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js'
      ]
    }
    return args
  })
}

在 public/index.html 里用 EJS 语法引入：

<% for (var i in htmlWebpackPlugin.options.cdn.js) { %>
  <script src="<%= htmlWebpackPlugin.options.cdn.js[i] %>"></script>
<% } %>

11.3 配置 HMR（热模块替换）和自动刷新

devServer: {
  hot: true,
  liveReload: true
}

11.4 构建不同环境的配置

publicPath: process.env.NODE_ENV === 'production'
  ? process.env.VUE_APP_PUBLIC_PATH
  : '/',
outputDir: process.env.VUE_APP_OUTPUT_DIR || 'dist'

11.5 配置静态资源目录

assetsDir: 'static'

12. 调试与排查建议

  • 配置生效检查：可在 vue.config.js 里 console.log 输出关键参数，或用 vue inspect > output.js 查看最终 webpack 配置。
  • 热更新失效：检查 devServer 的 hot 和 liveReload，以及是否有缓存未清理。
  • 代理不生效：确保前端请求路径和代理路径一致，注意 pathRewrite 设置。
  • 样式全局变量未生效：确认 loaderOptions 路径和写法无误。
  • 打包体积过大：用 webpack-bundle-analyzer 分析，排查大依赖、重复依赖，考虑使用 CDN。

13. 总结

  • vue.config.js 支持高度自定义，适用于大部分实际项目需求
  • 通过 configureWebpack、chainWebpack 可定制 webpack 行为
  • devServer、css、pluginOptions 等覆盖开发、构建、样式、插件等方方面面
  • 多用环境变量和条件判断，让配置更灵活
  • 遇到问题时善用官方文档和社区资源
VUE——Vue.config.js配置
weixin_63215361的博客
06-24 750
这段配置的意思是：在开发环境下，所有以 /api 开头的请求都会被代理到 http://vueshop.glbuys.com/，并且去掉 /api 前缀后再发送请求。
vue.config.js 文件的作用以及配置详解
Estrellayun_的博客
11-17 1155
vue.config.js 文件是 Vue CLI 项目中的配置文件，用于对 Vue 项目的构建、开发服务器等进行配置。
vue.config.js常用配置详解
12-13
使用vue-cli3.0搭建项目比之前更简洁，没有了build和config文件夹。 vue-cli3的一些服务配置都迁移到CLI Service里面了，对于一些基础配置和一些扩展配置需要在根目录新建一个vue.config.js文件进行配置 module.exports = { // 选项... } 基本路径 baseUrl从 Vue CLI 3.3 起已弃用使用publicPath来替代。 在开发环境下，如果想把开发服务器架设在根路径，可以使用一个条件式的值 module.exports = { publicPath: process.env.NODE_ENV === 'prod
vue.config.js 配置
热门推荐
muzidigbig的博客
04-13 4万+
vue.config.js配置项 vue-cli3 脚手架搭建完成后，项目目录中没有 vue.config.js 文件，需要手动创建 创建vue.config.js vue.config.js(相当于之前的webpack.config.js) 是一个可选的配置文件，如果项目的 (和package.json同级的) 根目录中存在这个文件，那么它会被@vue/cli-service自动加载。你也可以使用package.json中的vue字段，但是注意这种写法需要你严格遵照 JSON 的...
vue.config.js详细配置
L_R_H_的博客
07-22 3425
/ 使用 DefinePlugin 插件定义环境变量。
详解如何配置vue-cli3.0的vue.config.js
12-02
本文介绍了如何配置vue-cli3.0的vue.config.js，分享给大家，具体如下： vue-cli 3 英文文档 vue-cli 3 中文文档 webpack 4 plugins webpack-chain TLDR vue-cli 3 与 2 版本有很大区别 vue-cli 3 的 github 仓库由...
vue-cli3中vue.config.js配置教程详解
10-16
总之，`vue.config.js` 是 Vue CLI 3 的核心配置文件，通过它我们可以根据项目需求调整构建设置，如自定义输出目录、设置源码映射、配置代理服务器等。了解并熟练掌握这些配置，将极大地提升开发效率。在编写 `vue....
Vue CLI4 Vue.config.js标准配置(最全注释)
10-15
Vue.config.js 文件是 Vue CLI4 中用于自定义项目配置的地方，它允许开发者调整默认构建设置以适应特定项目的需求。以下是一些关键配置选项的详细说明： 1. **publicPath**: 这个配置项决定了生成的静态资源在生产...
vue.config.js完整配置-超详细
05-26
在 Vue 项目中，`vue.config.js` 文件是一个可选的配置文件，它允许开发者自定义项目的各种设置，以满足特定需求。这个文件通常位于项目的根目录下，如果使用了 `@vue/cli` 创建的项目，那么在初始化时该文件可能不...
Vue的 vue.config.js 配置
m0_69497411的博客
03-26 5905
是一个可选的配置文件，如果项目的根目录中存在这个文件，那么它会被自动加载。也可以使用中的vue字段，但是注意这种写法需要你严格遵照 JSON 的格式来写。
vue本地运行浏览器ip是本机Ip
yao_1063066968的博客
02-25 374
var os = require('os'), ip = '', ifaces = os.networkInterfaces() // 获取本机ip out: for (var i in ifaces) { for (var j in ifaces[i]) { var val = ifaces[i][j] if (val.family === 'IPv4' && val.address !== '127.0.0.1') { ip = val.address
Vue.config.js配置详解
weixin_45566730的博客
06-23 1064
对Vue.config.js文件的配置进行详细的讲解
vue.config.js配置详解
weixin_53607113的博客
07-19 960
vue.config.js配置
vue.config.js属性详解，附图文案例
最新发布
weixin_45075981的博客
03-14 2343
Vue 2 项目中。
Vue vue.config.js 的详解与配置
Allen-Ye博客
04-09 2万+
Vue的 vue.config.js 配置 1. 为什么要配置 vue.config.js 由于 vue-cli 3 也学习了 rollup 的零配置思路，所以项目初始化后，没有了以前熟悉的 build 目录，也就没有了 webpack.base.config.js、webpack.dev.config.js 、webpack.prod.config.js 等配置文件。 但是有些内容需要进行相关的配置，所以我们还是要创建一个vue.config.js来进行数据修改，比如代理啥的 2.里面的配置详解 vue.
vue.config.js的详解
Litt_White的博客
01-19 9388
vue.config.js配置详情（超级详细）
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

猩火燎猿

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值