Quasar makes use of some awesome development tools under its hood, like Webpack. One of the great things about Quasar is its handling of most of the complex configuration needed by the underlying tools for you. As a result, you don’t even need to know Webpack or any of the other development tools in order to use Quasar.
So what can you configure through the /quasar.config
file?
- Quasar components, directives and plugins that you’ll be using in your website/app
- Default Quasar Language Pack
- Icon libraries that you wish to use
- Default Quasar Icon Set for Quasar components
- Development server port, HTTPS mode, hostname and so on
- 您希望使用的 CSS 動畫
- 啟動檔案列表 (也決定了執行順序) – 這些檔案位於
/src/boot
中,說明您的應用程式如何在掛載根 Vue 元件之前初始化 - 要包含在 bundle 中的全域 CSS/Sass/… 檔案
- PWA manifest 和 Workbox 選項
- Electron Packager 和/或 Electron Builder
- 擴展 Webpack 設定
提示
您會注意到,變更這些設定中的任何一個都不需要您手動重新載入開發伺服器。Quasar 會偵測並重新載入必要的進程。您不會失去開發流程,因為您可以放鬆地坐著,讓 Quasar CLI 快速重新載入變更後的程式碼,甚至保持目前的狀態。這節省了您大量的時間!
警告
/quasar.config
檔案由 Quasar CLI 建置系統執行,因此這段程式碼直接在 Node 下執行,而不是在您的應用程式的上下文中執行。這表示您可以 require 像 ‘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 模式使用另一個全域 CSS 檔案,同時避免為其他模式載入任何此類檔案。
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 | 布林值 | 啟用 PreFetch 功能。 |
extras | 陣列 | 要從 @quasar/extras 套件匯入的內容。範例:[‘material-icons’, ‘roboto-font’, ‘ionicons-v4’] |
vendor | 物件 | 新增/移除到/從 vendor chunk 的檔案/第三方函式庫:{ 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 CLI 根據 “quasar dev” 參數和 Quasar 模式覆寫,以確保一切都正確設定。注意:如果您正在代理開發伺服器 (即使用雲端 IDE 或本地通道),請在 client
區段中將 webSocketURL
設定設定為您的公開應用程式 URL,以允許 Live Reload 和 Hot Module Replacement 等功能正常運作,如此處所述。
最常用的屬性是
屬性 | 類型 | 描述 |
---|---|---|
port | 數字 | 開發伺服器的埠 |
host | 字串 | 用於開發伺服器的本機 IP/Host |
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 憑證。但是,如果您想為您的 localhost 建立一個憑證,請查看 Filippo 的這篇部落格文章Filippo。然後您的 quasar.config file > 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 | Regex 陣列 | 如果 “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 ) 執行 hook。此時,開發伺服器已啟動並可供使用,如果您希望對其執行某些操作。可以使用 async/await 或直接傳回 Promise。 |
beforeBuild({ quasarConf }) | 函數 | 在 Quasar 為生產環境建置應用程式 ($ quasar build ) 之前執行 hook。此時,發佈資料夾尚未建立。可以使用 async/await 或直接傳回 Promise。 |
afterBuild({ quasarConf }) | 函數 | 在 Quasar 為生產環境建置應用程式 ($ quasar build ) 之後執行 hook。此時,發佈資料夾已建立並可供使用,如果您希望對其執行某些操作。可以使用 async/await 或直接傳回 Promise。 |
onPublish(opts) | 函數 | 如果請求發佈 ($ quasar build -P ),則在 Quasar 為生產環境建置應用程式且 afterBuild hook (如果指定) 已執行之後執行 hook。可以使用 async/await 或直接傳回 Promise。opts 是 {arg, distDir} 形式的物件,其中 “arg” 是提供給 -P 參數的引數 (如果有的話)。 |
publicPath | 字串 | 您的應用程式的公開路徑。預設情況下,它使用根目錄。當您的公開路徑是其他路徑時使用它,例如 “<protocol>://<domain>/some/nested/folder” – 在這種情況下,這表示發佈資料夾位於您的網路伺服器上的 “some/nested/folder” 中。 |
appBase | 字串 | 使用您的自訂值強制應用程式 base 標籤;僅在您真的知道自己在做什麼時才設定,否則您很容易損壞您的應用程式。強烈建議讓 @quasar/app-webpack 計算此值。 |
vueRouterBase | 字串 | 使用您的自訂值強制 vue router base;僅在您真的知道自己在做什麼時才設定,否則您很容易損壞您的應用程式。強烈建議讓 @quasar/app-webpack 計算此值。 |
vueRouterMode | 字串 | 設定 Vue Router 模式:‘hash’ 或 ‘history’。明智地選擇。History 模式也需要在您的部署網路伺服器上進行設定。 |
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 | 字串 | 要使用的 Source map 策略。 |
env | 物件 | 將屬性新增到 process.env ,您可以在您的網站/應用程式 JS 程式碼中使用它們。 |
gzip | 布林值/物件 | Gzip 發佈資料夾。當您用來提供內容的網路伺服器沒有 gzip 時很有用。如果以物件形式使用,則表示 compression-webpack-plugin 設定物件。 |
analyze | 布林值/物件 | 使用 webpack-bundle-analyzer 顯示建置 bundle 的分析。如果以物件形式使用,則表示 webpack-bundle-analyzer 設定物件。 |
vueCompiler | 布林值 | 包含 vue runtime + compiler 版本,而不是預設的 Vue runtime-only |
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 CLI 根據 dev/build 命令和 Quasar 模式自動設定。但是,如果您想覆寫某些屬性 (請確保您知道自己在做什麼),您可以這樣做
屬性 | 類型 | 描述 |
---|---|---|
extractCSS | 布林值 | 從 Vue 檔案中提取 CSS |
sourceMap | 布林值 | 使用 source maps |
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 文件頁面的深入分析。