quasar.config.js 配置详解

Quasar 在底层使用了一些很优秀的工具，例如 Webpack。 Quasar 的一大优点是它能够帮您处理底层工具所需的大部分复杂配置。因此，您甚至不需要了解 Webpack 或任何其他开发工具就可以使用 Quasar。

注意，使用脚手架创建的项目的根目录下有一个 /quasar.config.js 文件，Quasra CLI 几乎所有的行为都通过这个文件进行配置：

• 配置您的网站/app 使用哪些 Quasar 组件，指令和插件；
• 设置默认的 Quasar 语言包；
• 选择您喜欢的图标库；
• 配置 Quasar 组件使用的默认图标集合；
• 配置开发服务器的端口、HTTPS 模式、主机名等等；
• 配置您想用的 CSS 动画
• 配置启用哪些 Boot 文件 以及其执行顺序（位于 src/boot 目录下会在 Vue 根组件挂载之前被执行的文件）；
• 配置会被打包的全局 CSS/Sass… 文件；bundle
• SPA, PWA, Electron, Capacitor, Cordova, SSR, BEX (浏览器插件) 配置项；
• Electron Packager 和/或 Electron Builder
• 扩展底层工具的配置项，例如 Webpack 的配置项；

结构

基础

您会注意到 /quasar.config.js 导出一个带有一个 ctx （上下文 context）参数的函数，并返回一个对象。您可以通过这个上下文（context）动态的改变您的网站/app 的配置：

module.exports = function (ctx) { // 也可是一个异步的函数
  console.log(ctx)

  // 打印 ctx 的输出示例:
  {
    dev: true,
    prod: false,
    mode: { spa: true },
    modeName: 'spa',
    target: {},
    targetName: undefined,
    arch: {},
    archName: undefined,
    debug: undefined
  }
  // 上下文会根据您运行 "quasar dev" 或 "quasar build" 时传入的参数生成
}

例如，您可以在为特定模式（如 PWA）构建时加载一种字体，并为其他模式加载另一种字体：

module.exports = function (ctx) {
  extras: [
    ctx.mode.pwa // 我们只在 PWA 模式下加载此字体
      ? 'roboto-font'
      : null
  ]
}

或者您可以为 SPA 模式使用一个全局 CSS 文件，为 Cordova 模式使用另一个全局 CSS 文件，同时避免为其他模式加载任何这样的文件

module.exports = function (ctx) {
  css: [
    ctx.mode.spa ? 'app-spa.sass' : null, // 加载 /src/css/app-spa.sass
    ctx.mode.cordova ? 'app-cordova.sass' : null  // 加载 /src/css/app-cordova.sass
  ]
}

或者您可以将开发服务器的端口配置为：SPA 模式下为 8000，在 PWA 模式下为 9000，其他模式下为 9090

module.exports = function (ctx) {
  devServer: {
    port: ctx.mode.spa
      ? 8000
      : (ctx.mode.pwa ? 9000 : 9090)
  }
}

您也可以在返回 Quasar 配置之前进行异步工作:

module.exports = async function (ctx) {
  const data = await someAsyncFunction()
  return {
    // ... use "data"
  }
}

// 或者:
module.exports = function (ctx) {
  return new Promise(resolve => {
    // 在此进行异步工作:
    // 将 Quasar 配置传入 resolve() 函数返回
    resolve({
      //
    })
  })
}

可能性是无限的。

IDE 自动补全

您可以将导出的函数使用 configure() 包裹起来，则在配置时可获得 IDE 的自动补全提示 （通过 Typescript）：

const { configure } = require('quasar/wrappers')

module.exports = configure(function (ctx) {
  /* 配置项 */
})

配置项详解

我们来逐个看一下每个配置项：

Property: css

配置全局加载的来自 /src/css/ 目录下的 CSS/Stylus/SCSS/SASS/… 文件，除了会被默认加载的 theme （主题）文件

// quasar.config.js
return {
  css: [
    'app.sass', // 加载 /src/css/app.sass
    '~some-library/style.css' // 加载 node_modules/some-library/style.css
  ]
}

Property: vendor

默认情况下，由于性能和缓存的原因，任何来自 node_modules 的内容都会在打包时被注入到 vendor 块，然而，如果您想为这个特定的块添加/删除内容，那么您可以：

// quasar.config.js
return {
  vendor: {
    /* 可选的;
       禁用 vendor chunk: */ disable: true,

    add: [ 'src/plugins/my-special-plugin' ],
    remove: ['axios', 'vue$']
  }
}

Property: framework

告诉 CLI 导入哪些 Quasar 组件/指令/插件，使用哪个语言包，使用哪些图标库等。

只有当 “all” 被设置为 false 时，才需要填入 “components” 和 “directives”。

// quasar.config.js
return {
  // a list with all options (all are optional)
  framework: {
    // 自动导入策略，您可以配置：
    autoImportComponentCase: 'pascal', // or 'kebab' (default) or 'combined'

    /**
     * 在 Vue 文件中的 Quasar 组件可以被自动导入，但是还有一些特殊情况需要手动处理
     * （例如在 .js 或 .ts 文件中）
     * 您可以手动声明哪些 Quasar 组件/指令可以在任何地方都可以被使用。
     * @example [ 'QAvatar', 'QChip' ]
     */
    // components: [],
    // directives: [],

    // 启动的 Quasar 插件
    plugins: ['Notify' /* ... */],

    // Quasar 配置
    // 您会在需要使用时在文档中见到它
    config: { /* ... */ },

    iconSet: 'fontawesome-v6', // 选择 Quasar 图标库中的一个作为 Quasar 组件的默认图标库，也需要在  "extras" 配置项中指明
    lang: 'de', // 告诉 Quasar 为它自带的组件使用哪个语言包

    cssAddon: true // 添加 flex 响应式 CSS 类 是否开启 CSS 断点功能（注意代码体积会明显增大）
  }
}

更多关于 cssAddon 参考这里.

Property: devServer

Webpack 开发服务器配置项。看一下 完整的配置列表。为了确保正确的配置，一些属性会根据您使用的 Quasar 模式进行覆盖。注意：如果您正在代理开发服务器（如使用云 IDE），将请将 client 中的 webSocketURL 设置为您的应用程序的 public URL 以开启热更新之类的特性，请参考这里。

下面时一些常用的配置项：

使用 open 属性可以配置打开一个特定的浏览器而不是使用系统默认浏览器，在浏览器支持列表 页面查看可配置内容，其中的 options 字段就是您可以填入 quasar.config.js > devSever > open 中的内容。例如：

// quasar.config.js
// （下面的语法需要 @quasar/app-webpack v3.3+）

// 打开 Google Chrome
devServer: {
  open: {
    app: { name: 'google chrome' }
  }
}

// 打开 Firefox
devServer: {
  open: {
    app: { name: 'firefox' }
  }
}

// 打开 Google Chrome 并自动处理跨平台问题
const open = require('open')

devServer: {
  open: {
    app: { name: open.apps.chrome }
  }
}

当您设置 devServer > https: true 时，Quasar 会自动为您生成一个 SSL 证书，然而，如果您想使用自己的证书，那么可以参考这个博客：Filippo，然后您的 quasar.config.js > devServer > https 配置应该类似这样：

// quasar.config.js

devServer: {
  server: {
    type: 'https', // NECESSARY (alternative is type 'http')

    options: {
      // Use ABSOLUTE paths or path.join(__dirname, 'root/relative/path')
      key: "/path/to/server.key",
      pfx: "/path/to/server.pfx",
      cert: "/path/to/server.crt",
      ca: "/path/to/ca.pem",
      passphrase: 'webpack-dev-server' // do you need it?
    }
  }
}

您还可以配置自动打开远程 Vue Devtools：

// quasar.config.js

devServer: {
  vueDevtools: true
}

Docker 和 WSL 上的热更新问题

如果您使用的是 Docker 容器，则可能会发现 HMR（热更新）停止工作。HMR（热更新）依靠操作系统来提供有关监听更改文件的通知，这些可能对您的 Docker 容器不起作用。

通过使用轮询模式检查文件系统更改，可以实现一种权宜之计的解决方案。这可以通过以下方式实现：

// quasar.config.js

build: {
  // ...
  extendWebpack(cfg) {
    cfg.watchOptions = {
      aggregateTimeout: 200,
      poll: 1000,
    };
  },
// ...

Property: build

下面是 build 中一些 Quasar CLI 会根据命令（dev/build）和开发模式自动生成的属性。但是如果您想重写它们（非必要不要这么做），那么可以：

例如，如果您运行 “quasar build --debug” 那么 sourceMap and extractCSS 将会被设置为 “true” ，不管您如果配置。

Property: htmlVariables

您可以在此定义变量，然后再 src/index.template.html 文件中引用，就像下面这样：

// quasar.config.js
module.exports = function (ctx) {
  return {
    htmlVariables: {
      title: 'test name',
      some: {
        prop: 'my-prop'
      }
    }

然后（只是向您展示如何引用上述的变量）

<!-- src/index.template.html -->
<%= title %>
<%= some.prop %>

Property: sourceFiles

如果需要，可以使用此属性更改网站/应用程序的某些文件的默认名称。所有的路径都必须是一个相对于项目根目录的一个相对路径。

// default values:
sourceFiles: {
  rootComponent: 'src/App.vue',
  router: 'src/router',
  store: 'src/store',
  indexHtmlTemplate: 'src/index.template.html',
  registerServiceWorker: 'src-pwa/register-service-worker.js',
  serviceWorker: 'src-pwa/custom-service-worker.js',
  electronMain: 'src-electron/electron-main.js',
  electronPreload: 'src-electron/electron-preload.js'
}

为开发/生产设置不同的环境变量 env

请参考添加 process.env文档页面。

处理 Webpack 配置

更深层次的分析见处理 Webpack 文档页面。