Vue全家桶
Vue2

vue.config.js配置

# vue.config.js配置

在 Vue 项目的 vue.config.js 文件中，你可以配置多个方面的内容，以自定义构建过程、调整开发服务器设置、修改 Webpack 配置等。下面是一些常见的配置项：

# 1. 基本配置

# 1.1 `publicPath`(项目基础路径配置)

作用：设置项目的基础路径。默认为 '/'，表示项目将部署在根路径下。如果你的项目将部署在一个子路径下，需要设置为子路径名称。
```
module.exports = {
  publicPath: process.env.NODE_ENV === 'production' ? '/sub-path/' : '/'
};
```
1
2
3

# 1.2 `outputDir`(打包输出目录)

作用：指定打包生成的静态文件目录，默认是 dist。
```
module.exports = {
  outputDir: 'dist'
};
```
1
2
3

# 1.3 `assetsDir`(静态资源目录配置)

作用：配置生成的静态资源（如 js, css, img, fonts）目录，相对于 outputDir。
```
module.exports = {
  assetsDir: 'static'
};
```
1
2
3

# 1.4 `indexPath`(`index.html` 输出路径配置)

作用：指定生成的 index.html 的输出路径。

module.exports = {
  indexPath: 'index.html'
};

1
2
3

# 1.5 `filenameHashing`(文件名哈希配置)

作用：是否在生成的静态资源文件名中包含 hash，以便更好地控制缓存。
```
module.exports = {
  filenameHashing: true
};
```
1
2
3

# 2. 开发服务器配置

# 2.1 `devServer`

作用：配置开发服务器的一些选项，如代理、端口号、热更新等。

module.exports = {
  devServer: {
    port: 8080,  // 修改开发服务器端口号
    open: true,  // 开发服务器启动后自动打开浏览器
    proxy: {
      // 当访问 '/api' 开头的请求时，将其代理到后端服务器
      '/api': {
        target: 'http://localhost:3000',  // 目标服务器地址
        changeOrigin: true,  // 修改请求头中的 'Origin' 字段为目标地址
        pathRewrite: {
          '^/api': ''  // 将请求路径中的 '/api' 替换为空字符串，即去掉 '/api'
        },
        secure: false,  // 如果目标服务器使用的是自签名的 SSL 证书，则需要将此项设置为 false
        ws: false  // 如果需要代理 WebSocket，可以将此选项设置为 true
      }
    }
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

proxy 是 devServer 配置中的一个重要选项，它允许我们将开发服务器的请求代理到另一个服务器。这个功能在开发过程中非常有用，特别是在前后端分离的项目中，可以将前端请求的 API 地址代理到后端服务器，以避免跨域问题。

target:
- 作用：指定代理的目标服务器的地址。开发服务器接收到匹配的请求后，会将其转发到目标服务器。例如，如果前端请求 /api/user，则请求将被代理到 http://localhost:3000/user。
changeOrigin:
- 作用：在代理时更改请求头中的 Origin 字段。默认情况下，浏览器发送的请求会带有当前页面的 Origin。当我们将请求代理到另一个服务器时，可能会出现跨域问题。通过设置 changeOrigin: true，代理服务器会将请求的 Origin 修改为目标服务器的 Origin，从而避免跨域问题。
pathRewrite:
- 作用：重写请求路径。假设前端请求路径为 /api/user，我们希望将其代理到目标服务器的 /user 路径上，而不是 /api/user。这时就需要使用 pathRewrite。
- 该配置表示将路径中的 /api 替换为空字符串，即 /api/user 会被代理到 /user。
secure:
- 作用：如果目标服务器使用了自签名的 SSL 证书（即非可信的证书），将 secure 设置为 false 可以忽略证书验证。默认情况下，代理服务器会验证 SSL 证书的有效性，如果证书无效（如自签名证书），请求会失败。
ws:
- 作用：是否代理 WebSocket 协议。如果你的应用使用了 WebSocket 进行实时通信，需要将 ws 设置为 true。

# 2.2 解决跨域问题

前端解决跨域问题，通常只需要在 devServer.proxy 中配置 target 和 changeOrigin 两个选项。

target: 设置为你要代理的目标服务器的地址。
changeOrigin: 设置为 true，以确保请求头中的 Origin 字段被修改为目标服务器的地址，避免跨域问题。

这样，当前端发出请求时，开发服务器会将请求代理到目标服务器，从而绕过浏览器的同源策略，避免跨域错误。

这是最常用的、基本的跨域解决方案。其他配置选项如 pathRewrite、secure、ws 等可以根据具体需求来决定是否添加。

# 2.3 生产环境代理配置

devServer 相关配置（如 proxy）是用于本地开发环境的，当你运行 npm run serve 或 yarn serve 时，这些配置会被应用，用于启动本地开发服务器并处理跨域问题。
在生产环境下，Vue 项目通常已经被构建为静态文件，这些静态文件会被部署到 Web 服务器（如 Nginx、Apache）上，而 devServer 配置在这个阶段不会生效。

在生产环境下，Nginx 扮演着反向代理的角色，它会根据你的配置将客户端请求转发到相应的后端服务。例如，你可以在 Nginx 的配置文件中设置 API 请求的代理：

server {
 listen 80;  # 监听80端口，这是HTTP的默认端口
 server_name yourdomain.com;  # 你的域名，例如www.example.com

 location / {
     root /path/to/your/vue/project;  # Vue 项目编译后静态文件的存放路径
     try_files $uri $uri/ /index.html;  # 尝试访问文件，如果找不到则返回 index.html，适用于单页面应用（SPA）
 }

 location /api/ {  # 匹配所有以 /api/ 开头的请求
     proxy_pass http://your-backend-server.com;  # 将这些请求转发到你的后端服务器
     proxy_set_header Host $host;  # 将客户端请求的 Host 头部信息传递给后端服务器
     proxy_set_header X-Real-IP $remote_addr;  # 传递客户端的真实IP地址
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # 传递客户端的真实IP（包括经过的所有代理）
     proxy_set_header X-Forwarded-Proto $scheme;  # 传递请求使用的协议（http或https）
 }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 2.4 WebSocket 代理配置

在开发环境下，vue.config.js 中的 devServer 配置的 ws 选项可以用于配置 WebSocket 的代理，这在本地开发服务器上是有效的。
但是，在生产环境下，vue.config.js 中的 devServer 配置，包括 ws 选项，将不再生效。因此，如果你在生产环境中需要支持 WebSocket，需要在 Web 服务器（如 Nginx）上进行相应的配置。

1. 基本配置结构

server {
    listen 80;  # 监听端口，通常是 80（HTTP）或 443（HTTPS）
    server_name yourdomain.com;  # 服务器的域名

    location / {
        root /path/to/your/vue/project;  # Vue 项目的静态文件路径
        index index.html;
        try_files $uri $uri/ /index.html;  # 处理 Vue 路由
    }

    # WebSocket 代理配置
    location ^~ /websocket {  # 匹配 WebSocket 请求路径
        proxy_pass http://服务器ip:8080/websocket;  # 代理到 WebSocket 服务器
        proxy_http_version 1.1;  # 指定使用 HTTP/1.1 协议，这是 WebSocket 所必需的

        # 确保升级 HTTP 连接到 WebSocket 的请求头被正确设置
        proxy_set_header Upgrade $http_upgrade;  
        proxy_set_header Connection "Upgrade";

        # 传递客户端的主机信息和 IP 地址
        proxy_set_header Host $host;  
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

proxy_pass http://服务器ip:8080/websocket;
- 该指令将请求转发到指定的 WebSocket 服务器，路径为 /websocket。
proxy_http_version 1.1;
- WebSocket 需要使用 HTTP/1.1 协议，而非 HTTP/1.0，因为 HTTP/1.1 支持持久连接，这是 WebSocket 通信的基础。
proxy_set_header Upgrade $http_upgrade;
- Upgrade 头告诉服务器升级协议，从 HTTP/1.1 升级为 WebSocket。
proxy_set_header Connection "Upgrade";
- 该指令设置 Connection 头为 Upgrade，表明此次连接应该从 HTTP 升级到 WebSocket。
proxy_set_header Host $host;
- 保持请求的主机头信息与客户端请求一致，便于后端服务器识别请求来源。
proxy_set_header X-Real-IP $remote_addr;
- 将客户端的真实 IP 地址传递给后端服务器，后端可以通过 X-Real-IP 获取客户端的 IP。
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- 该头用于记录代理链条中的所有客户端 IP 地址。如果请求经过多个代理服务器，该头会包含每个代理服务器的 IP。

优化建议

安全性配置: 如果你的 WebSocket 服务器使用 HTTPS，确保 proxy_pass 使用 https:// 协议，并且启用了 SSL 相关配置。
连接保持: 可以通过 proxy_read_timeout 和 proxy_send_timeout 来配置 WebSocket 连接的保持时间，以应对长时间未传输数据的场景。

# 3. Webpack 配置

# 3.1 `configureWebpack`(直接修改 Webpack 配置)

作用：直接修改或扩展 Webpack 配置。你可以在这里添加插件、优化选项等。

module.exports = {
  configureWebpack: {
    plugins: [
      new MyAwesomeWebpackPlugin()
    ]
  }
};

1
2
3
4
5
6
7

# 3.2 `chainWebpack`(链式修改 Webpack 配置)

作用：通过链式调用的方式，进一步细粒度地修改 Webpack 配置。适用于需要更复杂自定义 Webpack 配置的场景。

module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .loader('vue-loader')
      .tap(options => {
        // 修改 options...
        return options;
      });
  }
};

1
2
3
4
5
6
7
8
9
10
11
12

# 4. CSS 相关配置

# 4.1 `css.loaderOptions`

作用：向 CSS 相关的 loader 传递选项。例如，可以在这里配置 scss 全局变量。

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

1
2
3
4
5
6
7
8
9

# 4.2 `css.sourceMap`

作用：是否为 CSS 开启 source map。一般在开发环境下开启，以便调试。

module.exports = {
  css: {
    sourceMap: process.env.NODE_ENV !== 'production'
  }
};

1
2
3
4
5

# 5. 插件配置

# 5.1 `pluginOptions`

作用：向第三方插件传递选项。

module.exports = {
  pluginOptions: {
    foo: {
      // 插件foo的配置
    }
  }
};

1
2
3
4
5
6
7

# 6. 多页应用配置

# 6.1 `pages`

作用：配置多页应用。Vue CLI 默认支持单页面应用，通过 pages 选项可以配置多页应用。

module.exports = {
  pages: {
    index: {
      entry: 'src/main.js',
      template: 'public/index.html',
      filename: 'index.html'
    },
    subpage: {
      entry: 'src/subpage/main.js',
      template: 'public/subpage.html',
      filename: 'subpage.html'
    }
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 7. 环境变量配置 (env)

在 Vue 项目中，可以通过 .env 文件来配置不同环境下的环境变量。这些变量可以用于在开发、测试和生产等不同环境中定制化应用的行为。例如，你可以为开发环境配置一个 API 地址，为生产环境配置另一个 API 地址。

# 7.1 配置环境变量

创建 .env 文件： 在项目的根目录下，你可以创建多个 .env 文件，用于不同的环境。例如：
- .env.development：开发环境的配置文件。
- .env.production：生产环境的配置文件。
- .env.test：测试环境的配置文件。
在 .env 文件中配置变量：环境变量的名称需要以 VUE_APP_ 为前缀，这样才能被 Vue 项目所识别和使用。
```
# .env.development
VUE_APP_API_BASE_URL=http://localhost:3000
VUE_APP_ENV_NAME=development
```
1
2
3
```
# .env.production
VUE_APP_API_BASE_URL=https://api.production.com
VUE_APP_ENV_NAME=production
```
1
2
3
在上面的示例中，我们为开发环境和生产环境分别配置了 VUE_APP_API_BASE_URL 和 VUE_APP_ENV_NAME 变量。

笔记

文件名 .env.development 是为了让 Vue CLI 知道这是哪个环境的配置文件，Vue CLI 根据文件名选择加载。
VUE_APP_ENV_NAME=development 是你自己定义的环境变量，可以用来在代码中判断当前环境。这个变量名和文件名之间没有直接的关联或要求它们一致。

# 7.2 使用环境变量

在 Vue 组件中使用环境变量：你可以在 Vue 组件的代码中通过 process.env 访问这些环境变量。

export default {
  data() {
    return {
      apiUrl: process.env.VUE_APP_API_BASE_URL, // 使用配置的 API 地址
      envName: process.env.VUE_APP_ENV_NAME // 使用配置的环境名称
    };
  },
  created() {
    console.log(`当前环境：${this.envName}`);
    console.log(`API 地址：${this.apiUrl}`);
  }
};

1
2
3
4
5
6
7
8
9
10
11
12

process.env.VUE_APP_API_BASE_URL：通过 process.env 对象访问环境变量。
该变量会根据当前运行的环境（开发、生产、测试）自动获取相应的值。

在项目配置文件中使用环境变量：你也可以在项目的配置文件中使用这些环境变量。例如在 vue.config.js 中：

module.exports = {
  publicPath: process.env.NODE_ENV === 'production' ? '/prod/' : '/',
  devServer: {
    proxy: {
      '/api': {
        target: process.env.VUE_APP_API_BASE_URL, // 使用环境变量配置代理目标
        changeOrigin: true,
        pathRewrite: { '^/api': '' }
      }
    }
  }
};

1
2
3
4
5
6
7
8
9
10
11
12

在 vue.config.js 中，你可以使用 process.env.VUE_APP_API_BASE_URL 来动态配置代理的目标地址。

# 7.3 Vue CLI 的加载顺序

当你启动 Vue 项目时，Vue CLI 会根据你使用的环境自动选择加载相应的 .env 文件。加载顺序如下：

所有环境：首先加载 .env 和 .env.local 文件中的配置。
特定环境：接着加载 .env.[mode] 和 .env.[mode].local 文件中的配置。

例如，当你运行 npm run serve 或 yarn serve 命令时，Vue CLI 会识别当前环境为 development，并按以下顺序加载文件：

.env - 所有环境通用的配置。
.env.local - 所有环境通用但本地特有的配置。
.env.development - 仅在 development 环境下使用的配置。
.env.development.local - 仅在 development 环境下使用的本地特有配置。

注意事项

变量前缀：所有自定义环境变量必须以 VUE_APP_ 为前缀。如果不以这个前缀命名，Vue 项目将不会识别它们。
访问方式：在代码中，使用 process.env.VUE_APP_XXX 的方式访问环境变量。
动态构建：构建时，Vue CLI 会根据环境选择相应的 .env 文件，并将变量注入到应用中。

# 8. 启用或禁用特定功能

# 8.1 `lintOnSave`(代码格式校验)

作用：是否在保存时进行代码格式校验，默认启用 eslint。

module.exports = {
  lintOnSave: process.env.NODE_ENV !== 'production'
};

1
2
3

将 lintOnSave 设置为 false 可以关闭 eslint 的语法检查。这样，当你保存文件时，eslint 不会自动进行代码格式校验。
```
module.exports = {
  lintOnSave: false  // 关闭 eslint 语法检查
};
```
1
2
3
这样配置后，无论你是在开发环境还是生产环境下，eslint 都不会对代码进行语法检查。

# 8.2 `runtimeCompiler`(运行时编译器)

作用：是否使用包含运行时编译器的 Vue 构建版本。
```
module.exports = {
  runtimeCompiler: true
};
```
1
2
3

# 9. 生产环境优化

# 9.1 `productionSourceMap`

作用：是否在生产环境下生成 source map 文件。关闭可以减少包体积。
```
module.exports = {
  productionSourceMap: false
};
```
1
2
3

# 9.2 `parallel`(多线程构建)

作用：是否启用多线程构建，提升构建速度。

module.exports = {
  parallel: require('os').cpus().length > 1
};

1
2
3

通过以上这些配置项，你可以灵活地定制 Vue 项目的构建流程、开发环境以及特定功能。

编辑此页

上次更新: 2025/01/30, 23:55:43

← vue-cli Vue组件→

vue.config.js配置

# vue.config.js配置

# 1. 基本配置

# 1.1 publicPath(项目基础路径配置)

# 1.2 outputDir(打包输出目录)

# 1.3 assetsDir(静态资源目录配置)

# 1.4 indexPath(index.html 输出路径配置)

# 1.5 filenameHashing(文件名哈希配置)

# 2. 开发服务器配置

# 2.1 devServer

# 2.2 解决跨域问题

# 2.3 生产环境代理配置

# 2.4 WebSocket 代理配置

# 3. Webpack 配置

# 3.1 configureWebpack(直接修改 Webpack 配置)

# 3.2 chainWebpack(链式修改 Webpack 配置)

# 4. CSS 相关配置

# 4.1 css.loaderOptions

# 4.2 css.sourceMap

# 5. 插件配置

# 5.1 pluginOptions

# 6. 多页应用配置

# 6.1 pages

# 7. 环境变量配置 (env)

# 7.1 配置环境变量

# 7.2 使用环境变量

# 7.3 Vue CLI 的加载顺序

# 8. 启用或禁用特定功能

# 8.1 lintOnSave(代码格式校验)

# 8.2 runtimeCompiler(运行时编译器)

# 9. 生产环境优化

# 9.1 productionSourceMap

# 9.2 parallel(多线程构建)

# 1.1 `publicPath`(项目基础路径配置)

# 1.2 `outputDir`(打包输出目录)

# 1.3 `assetsDir`(静态资源目录配置)

# 1.4 `indexPath`(`index.html` 输出路径配置)

# 1.5 `filenameHashing`(文件名哈希配置)

# 2.1 `devServer`

# 3.1 `configureWebpack`(直接修改 Webpack 配置)

# 3.2 `chainWebpack`(链式修改 Webpack 配置)

# 4.1 `css.loaderOptions`

# 4.2 `css.sourceMap`

# 5.1 `pluginOptions`

# 6.1 `pages`

# 8.1 `lintOnSave`(代码格式校验)

# 8.2 `runtimeCompiler`(运行时编译器)

# 9.1 `productionSourceMap`

# 9.2 `parallel`(多线程构建)