Quasar 在其引擎盖下使用了一些很棒的开发工具,例如 Webpack。Quasar 的一大优点是它为您处理了底层工具所需的大多数复杂配置。因此,即使您不知道 Webpack 或任何其他开发工具,也可以使用 Quasar。
那么,您如何通过 /quasar.config
文件进行配置呢?
- 您将在网站/应用程序中使用的 Quasar 组件、指令和插件
- 默认的 Quasar 语言包
- 您想使用的 图标库
- 用于 Quasar 组件的默认 Quasar 图标集
- 开发服务器端口、HTTPS 模式、主机名等
- 您想使用的 CSS 动画
- 引导文件 列表(也决定执行顺序)——位于
/src/boot
中的文件,用于指示在挂载根 Vue 组件之前如何初始化应用程序 - 要包含在捆绑包中的全局 CSS/Sass/… 文件
- PWA 清单 和 Workbox 选项
- Electron Packager 和/或 Electron Builder
- 扩展 Webpack 配置
提示
您会注意到,更改任何这些设置都不需要您手动重新加载开发服务器。Quasar 会检测并重新加载必要的进程。您不会失去开发流程,因为您只需坐下来,让 Quasar CLI 快速重新加载更改后的代码,甚至保持当前状态。这可以节省您大量时间!
警告
Quasar CLI 构建系统运行 /quasar.config
文件,因此此代码在 Node 下直接运行,而不是在应用程序的上下文中运行。这意味着您可以像 ‘fs’、‘path’、‘webpack’ 那样导入模块。确保您在此文件中要使用的 ES 功能受 Node 版本 支持(应该是 >= 14)。
结构
基础知识
您会注意到 /quasar.config
文件导出一个函数,该函数接受一个 ctx
(上下文)参数并返回一个对象。这使您可以根据此上下文动态更改网站/应用程序配置
module.exports = function (ctx) { // can be async too
console.log(ctx)
// Example output on console:
{
dev: true,
prod: false,
mode: { spa: true },
modeName: 'spa',
target: {},
targetName: undefined,
arch: {},
archName: undefined,
debug: undefined
}
// context gets generated based on the parameters
// with which you run "quasar dev" or "quasar build"
}
这意味着,例如,您可以在为特定模式(如 PWA)构建时加载一种字体,而为其他模式加载另一种字体
module.exports = function (ctx) {
extras: [
ctx.mode.pwa // we're adding only if working on a PWA
? 'roboto-font'
: null
]
}
或者,您可以为 SPA 模式使用一个全局 CSS 文件,为 Cordova 模式使用另一个文件,同时避免为其他模式加载任何此类文件。
module.exports = function (ctx) {
css: [
ctx.mode.spa ? 'app-spa.sass' : null, // looks for /src/css/app-spa.sass
ctx.mode.cordova ? 'app-cordova.sass' : null // looks for /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"
}
}
// or:
module.exports = function (ctx) {
return new Promise(resolve => {
// some async work then:
// resolve() with the quasar config
resolve({
//
})
})
}
可能性是无限的。
IDE 自动完成
您可以使用 configure()
助手来包装返回的函数,以获得更好的 IDE 自动完成体验(通过 Typescript)
const { configure } = require('quasar/wrappers')
module.exports = configure(function (ctx) {
/* configuration options */
})
要配置的选项
让我们逐一查看每个选项
属性 | 类型 | 描述 |
---|---|---|
css | 数组 | 来自 /src/css/ 的全局 CSS/Sass/… 文件,除了主题文件,这些文件默认包含在内。 |
preFetch | 布尔值 | 启用 预取功能。 |
extras | 数组 | 要从 @quasar/extras 包中导入的内容。示例:[‘material-icons’, ‘roboto-font’, ‘ionicons-v4’] |
vendor | 对象 | 向供应商块添加/移除文件/第三方库:{ add: […], remove: […] }。 |
supportTS | 布尔值/对象 | 添加对 TypeScript 的支持。 更多信息 |
htmlVariables | 对象 | 添加您可以在 /index.html 或 /src/index.template.html 中使用的变量。 |
framework | 对象/字符串 | 要导入的 Quasar 组件/指令/插件,要使用的 Quasar 语言包,要用于 Quasar 组件的 Quasar 图标集。 |
animations | 对象/字符串 | 要导入的 CSS 动画。示例:[‘bounceInLeft’, ‘bounceOutRight’] |
devServer | 对象 | Webpack devServer 选项。某些属性会根据您使用的 Quasar 模式进行覆盖,以确保正确的配置。注意:如果您要代理开发服务器(即使用云 IDE),请将 public 设置设置为您的公共应用程序 URL。 |
构建 | 对象 | 构建配置选项。 |
sourceFiles | 对象 | 更改应用程序各个部分的默认名称。 |
cordova | 对象 | Cordova 特定的 配置。 |
capacitor | 对象 | Quasar CLI Capacitor 特定的 配置。 |
pwa | 对象 | PWA 特定的 配置。 |
ssr | 对象 | SSR 特定的 配置。 |
electron | 对象 | Electron 特定的 配置。 |
属性:css
来自 /src/css/
的全局 CSS/Sass/… 文件,除了主题文件,这些文件默认包含在内。
return {
css: [
'app.sass', // referring to /src/css/app.sass
'~some-library/style.css' // referring to node_modules/some-library/style.css
]
}
属性:vendor
默认情况下,来自 node_modules
的所有内容都将被注入到 vendor chunk 中,以提高性能和缓存效率。但是,如果您想向该特殊 chunk 中添加或删除内容,可以按照以下方法操作。
return {
vendor: {
/* optional;
disables vendor chunk: */ disable: true,
add: [ 'src/plugins/my-special-plugin' ],
remove: ['axios', 'vue$']
}
}
属性:framework
告诉 CLI 要导入哪些 Quasar 组件/指令/插件,使用哪个 Quasar I18n 语言包,使用哪个图标集用于 Quasar 组件等等。
如果将 “all” 设置为 false
,则仅在填充 “components” 和 “directives” 时才需要。
return {
// a list with all options (all are optional)
framework: {
// is using "auto" import strategy, you can also configure:
autoImportComponentCase: 'pascal', // or 'kebab' (default) or 'combined'
// For special cases outside of where auto-import can have an impact
// (example: vue components written in .js files instead of .vue),
// you can manually specify Quasar components/directives to be available everywhere:
//
// components: [],
// directives: [],
// Quasar plugins
plugins: ['Notify' /* ... */],
// Quasar config
// You'll see this mentioned for components/directives/plugins which use it
config: { /* ... */ },
iconSet: 'fontawesome-v6', // requires icon library to be specified in "extras" section too,
lang: 'de', // Tell Quasar which language pack to use for its own components
cssAddon: true // Adds the flex responsive++ CSS classes (noticeable bump in footprint)
}
}
有关 cssAddon 的更多信息,请 点击这里。
属性:devServer
Webpack devServer 选项。请查看 完整选项列表。其中一些选项将根据“quasar dev”参数和 Quasar 模式被 Quasar CLI 覆盖,以确保所有内容都正确设置。注意:如果您正在代理开发服务器(例如,使用云 IDE 或本地隧道),请在 client
部分中设置 webSocketURL
设置为您的公共应用程序 URL,以允许实时重新加载和热模块替换等功能正常工作,如 这里所述。
最常用的属性是
属性 | 类型 | 描述 |
---|---|---|
port | 数字 | 开发服务器的端口 |
host | 字符串 | 用于开发服务器的本地 IP/主机 |
open | 布尔值/对象 | 除非设置为 false ,否则 Quasar 将自动打开一个指向开发服务器地址的浏览器。适用于 SPA、PWA 和 SSR 模式。使用 open 包参数。有关更多详细信息,请参见下文。 |
proxy | 对象/数组 | 当您有一个单独的 API 后端开发服务器并且希望在同一个域上发送 API 请求时,代理某些 URL 可能很有用。 |
devMiddleware | 对象 | 提供给 webpack-dev-middleware v4 的配置 |
server | 对象 | 在这里,您可以配置 HTTPS 而不是 HTTP(见下文) |
onBeforeSetupMiddleware | 函数 | 在 webpack-dev-server 应用其自己的配置之前,配置开发中间件。 |
onAfterSetupMiddleware | 函数 | 在 webpack-dev-server 应用其自己的配置之后,配置开发中间件。 |
使用 open
属性以特定浏览器打开,而不是使用操作系统的默认浏览器(查看 支持的值)。在之前的链接中描述的 options
参数是您应该在 quasar.config 文件> devSever > open 中配置的内容。以下是一些示例
// (syntax below requires @quasar/app-webpack v3.3+)
// opens Google Chrome
devServer: {
open: {
app: { name: 'google chrome' }
}
}
// opens Firefox
devServer: {
open: {
app: { name: 'firefox' }
}
}
// opens Google Chrome and automatically deals with cross-platform issues:
const open = require('open')
devServer: {
open: {
app: { name: open.apps.chrome }
}
}
当您在 /quasar.config
文件中设置 devServer > server > type: 'https'
时,Quasar 将自动为您生成 SSL 证书。但是,如果您想自己为本地主机创建一个证书,请查看 Filippo 的这篇博客文章。然后您的 quasar.config 文件> devServer > server
应该看起来像这样
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
devServer: {
vueDevtools: true
}
Docker 和 WSL 中 HMR 问题
如果您使用 Docker 容器,您可能会发现 HMR 停止工作。HMR 依赖于操作系统来提供有关更改文件的通知,这可能不适用于您的 Docker 容器。
可以使用轮询模式来检查文件系统更改,从而实现一个权宜之计的解决方案。可以使用以下方法启用它:
build: {
// ...
extendWebpack(cfg) {
cfg.watchOptions = {
aggregateTimeout: 200,
poll: 1000,
};
},
// ...
属性:build
属性 | 类型 | 描述 |
---|---|---|
transpile | 布尔值 | 启用或禁用 Babel 转换。 |
transpileDependencies | 正则表达式数组 | 如果 “transpile” 设置为 “false”,则不适用。添加要使用 Babel 转换的依赖项(来自 node_modules,默认情况下不进行转换)。例如:[ /my-dependency/, ...] |
showProgress | 布尔值 | 在编译时显示进度条。 |
transformAssetUrls | 对象 | 添加对自定义标签属性的资产引用的支持。例如:{ 'my-img-comp': 'src', 'my-avatar': [ 'src', 'placeholder-src' ]} |
extendWebpack(cfg) | 函数 | 扩展 Quasar CLI 生成的 Webpack 配置。等效于 chainWebpack(),但您可以直接访问 Webpack 配置对象。 |
chainWebpack(chain) | 函数 | 扩展 Quasar CLI 生成的 Webpack 配置。等效于 extendWebpack(),但使用 webpack-chain 代替。 |
beforeDev({ quasarConf }) | 函数 | 在 $ quasar dev 命令运行之前,准备外部服务,例如启动一些后端或应用程序依赖的任何其他服务。可以使用 async/await 或直接返回 Promise。 |
afterDev({ quasarConf }) | 函数 | 在 Quasar 开发服务器启动后运行钩子($ quasar dev )。此时,开发服务器已启动并可用,如果您想对其进行操作。可以使用 async/await 或直接返回 Promise。 |
beforeBuild({ quasarConf }) | 函数 | 在 Quasar 构建应用程序以供生产使用之前运行钩子($ quasar build )。此时,可分发文件夹尚未创建。可以使用 async/await 或直接返回 Promise。 |
afterBuild({ quasarConf }) | 函数 | 在 Quasar 构建应用程序以供生产使用之后运行钩子($ quasar build )。此时,可分发文件夹已创建并可用,如果您想对其进行操作。可以使用 async/await 或直接返回 Promise。 |
onPublish(opts) | 函数 | 如果请求发布($ quasar build -P ),则在 Quasar 构建应用程序以供生产使用并执行 afterBuild 钩子(如果指定)之后运行钩子。可以使用 async/await 或直接返回 Promise。 opts 是形式为 {arg, distDir} 的对象,其中 “arg” 是提供给 -P 参数的(如果有)参数。 |
publicPath | 字符串 | 应用程序的公共路径。默认情况下,它使用根目录。当您的公共路径是其他内容时,例如“<protocol>://<domain>/some/nested/folder” - 在这种情况下,这意味着可分发文件位于您的 Web 服务器上的 “some/nested/folder” 中。 |
appBase | 字符串 | 使用自定义值强制执行应用程序基本标签;仅在您 **真正** 知道自己在做什么时才配置,否则您可能会很容易地破坏您的应用程序。强烈建议让 @quasar/app-webpack 计算它。 |
vueRouterBase | 字符串 | 使用自定义值强制执行 vue 路由器基本路径;仅在您 **真正** 知道自己在做什么时才配置,否则您可能会很容易地破坏您的应用程序。强烈建议让 @quasar/app-webpack 计算它。 |
vueRouterMode | 字符串 | 设置 Vue 路由器模式:“hash” 或 “history”。明智地选择。历史模式也需要在您的部署 Web 服务器上进行配置。 |
htmlFilename | 字符串 | 默认为 ‘index.html’。 |
ssrPwaHtmlFilename | 字符串 | 用于 SSR+PWA 模式。默认为 ‘offline.html’。 |
productName | 字符串 | 默认值取自 package.json > productName 字段。 |
distDir | 字符串 | Quasar CLI 应该生成可分发文件的文件夹。相对于项目根目录的相对路径。默认为 ‘dist/{ctx.modeName}’。适用于除 Cordova 之外的所有模式(Cordova 强制设置为 src-cordova/www )。 |
ignorePublicFolder | 布尔值 | 忽略 /public 文件夹。如果您依赖于静态文件夹,则需要自己配置它(在 Quasar 之外或通过 extendWebpack/chainWebpack),因此请确保您知道自己在做什么。 |
devtool | 字符串 | 要使用的源映射 策略。 |
env | 对象 | 向 process.env 添加可以在网站/应用程序 JS 代码中使用的属性。 |
gzip | 布尔值/对象 | 压缩可分发文件。当您要提供内容的 Web 服务器没有 gzip 时,这很有用。如果使用对象,则它表示压缩-webpack-plugin 配置对象。 |
analyze | 布尔值/对象 | 使用 webpack-bundle-analyzer 显示构建包的分析结果。如果使用对象,则它表示 webpack-bundle-analyzer 配置对象。 |
vueCompiler | 布尔值 | 包括 vue 运行时 + 编译器版本,而不是默认的 Vue 运行时版本。 |
uglifyOptions | 对象 | JS 缩小选项。 完整列表 |
htmlMinifyOptions | 对象 | (需要 @quasar/app-webpack v3.10.2+) html-minifier 的缩小选项。 完整列表 |
vueLoaderOptions | 对象 | 用于 vue-loader 的选项(compilerOptions、compiler、transformAssetUrls 等)。 |
scssLoaderOptions | 对象 | 要提供给 sass-loader 用于 .scss 文件的选项。例如:scssLoaderOptions: { additionalData: ‘@import “src/css/abstracts/_mixins.scss”;’} |
sassLoaderOptions | 对象 | 要提供给 sass-loader 用于 .sass 文件的选项。 |
stylusLoaderOptions | 对象 | 要提供给 stylus-loader 的选项。 |
lessLoaderOptions | 对象 | 要提供给 less-loader 的选项。 |
以下 build
属性将根据开发/构建命令和 Quasar 模式由 Quasar CLI 自动配置。但是,如果您想覆盖一些属性(确保您知道自己在做什么),您可以这样做。
属性 | 类型 | 描述 |
---|---|---|
extractCSS | 布尔值 | 从 Vue 文件中提取 CSS |
sourceMap | 布尔值 | 使用源映射 |
minify | 布尔值 | 缩小代码(html、js、css) |
例如,如果您运行“quasar build --debug”,则无论您配置了什么,sourceMap 和 extractCSS 都将设置为 “true”。
属性:htmlVariables
您可以定义然后在 /index.html 或 /src/index.template.html 中引用变量,如下所示
module.exports = function (ctx) {
return {
htmlVariables: {
title: 'test name',
some: {
prop: 'my-prop'
}
}
然后(只是一个示例,展示了如何引用上面定义的变量,在本例中为 title
)
<%= title %>
<%= some.prop %>
属性: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'
}
示例设置开发/构建环境
请参考我们文档中的添加到 process.env部分。
处理 Webpack 配置
关于处理 Webpack的深入分析文档页面。