專案升級之路的系列文章是紀錄我將Composition API與Vite 導入到公司專案的過程. 記錄的範圍只包含升級Vue 以及Vue 相關的libraries (Vuex/Router/i18n/Jest)與解決相容性錯誤的問題. 這些升級的事項發生在2022/08, 日後在做這類升級時, 或許官方會出更多相容性版本, 就可能不會發生以下的問題
這系列文章包含這些章節
[Vue] 專案升級之路 — Composition API 篇
這篇文章是用來記錄把Vite 導入到公司專案的過程, 原本的專案是用VueCLI 建立專案的架構, 預設的local server是用Webpack, 為了能夠提升啟動速度, 所以決定試試看是否能夠導入Vite, 並將Webpack 取代
最後測試結果
取代前:
使用Vue CLI內建的Webpack 啟動local server
啟動時間需要約: 1minue
取代後:
使用Vite 起動local server
啟動時間需要約: 2–3sencods
更換紀錄
Vite 官方文件
Node.js 最低支援版本
- 14.18+
- 16+
Vite可支援的Vue 版本
Vite 目前提供了幾個plugin給Vue 的各個版本, 讓Vue 的開發者可以使用Vite
Vue 3 SFC support via @vitejs/plugin-vue
Vue 3 JSX support via @vitejs/plugin-vue-jsx
Vue 2.7 support via @vitejs/plugin-vue2
Vue <2.7 support via vite-plugin-vue2可以依照自己Vue的版本選擇對應的plugin 安裝
Installation
npm i -D vite因為之後我為了將我的專案升級到Vue2.7 所以我另外安裝相容的plugin
npm i -D @vitejs/plugin-vue2Package.json
{
"scripts": {
"dev": "vite", // start dev server, aliases: `vite dev`, `vite serve`
"build": "vite build", // build for production
"preview": "vite preview" // locally preview production build
}
}Breaking Changes
Upgrade the plugins if installed
- stylelint(`^12.0.0` -> `^14.9.1`)
- stylelint-config-recommended-scss (`^4.0.0` -> `^7.0.0`)
- stylelint-config-standard (`^19.0.0` -> `^26.0.0`)
- stylelint-scss (`^3.12.1` -> `^4.3.0`)
- node-sass(`^4.13.1` -> `^7.0.1`)SFC 內所有import 的檔案都要加入file extension
webpack 可以幫忙處理parse import的檔案, 因此可以省略副檔名, 但Vite 沒有, 若要在Vite server 也可以省略不寫副檔名, 依然仍可內有設定
官網教學: https://vitejs.dev/config/shared-options.html#resolve-extensions
不過官方已經不推薦這種寫法, 所以建議還是補上去.
快速補上去的方式可參考先前的文章
啟動有HTTPS的local server
如果用webpack 啟動local server時, 若要使用HTTPS, 可在vue-cli-service serve的指令加入 “--https“, 這樣server 啟動的時候, 就是https://.x.x.x.x.
如果是Vite的話, 則需要安裝@vitejs/plugin-basic-ssl.
// vite.config.js
import basicSsl from '@vitejs/plugin-basic-ssl'
export default {
plugins: [
basicSsl()
]
}使用.env.[mode]內的變數
官網文件教學: https://vitejs.dev/guide/env-and-mode.html#env-variables-and-modes
原本在VueCLI 的專案中, 若在.env 內宣告自定義的變數, 如
// .env.test
VUE_APP_CUSTOM_VERSION=1.0現在如果要取得VUE_APP_CUSTOM_VERSION, 則需要改成這樣
// .env.test
VITE_APP_CUSTOM_VERSION=1.0另外原本取得變數的方式是
process.env.VUE_APP_CUSTOM_VERSION在Vite裡面也需要改成
import.meta.env.VITE_APP_CUSTOM_VERSION動態載入圖片
當原本在VueCLI 的專案時, 因為使用webpack 來pre-build 專案程式碼, 而webpack 可以將使用CommonJS的語法編譯成browser 可以看得懂的程式碼, 所以可以用 require(xxx) 這樣的方式來動態顯示圖片
<img
:src="require(`@/assets/images/image.svg`)"
>而Vite 預設是使用esbuild來pre-build檔案, 而esbuild並不會處理CommonJS的語法, 除非再另外引入plugin:vite-plugin-commonjs(reference). 而官方有提供新的方式: import.meta.url + URL constructor,
image = new URL(`/src/assets/images/image.svg`, import.meta.url).href;官網教學文件: https://vitejs.dev/guide/assets.html#new-url-url-import-meta-url
根據官網敘述, 利用esbuild 原生的語法import.meta.url可以取得image 在專案內的相對位置, 再搭配瀏覽器環境原生的語法URL constructor, 取得可以讓JavaScript 解析的完整路徑
另外, 在production 模式下, Vite 也會自動轉換成編譯後的路徑, 所以無需再多做設定
安裝SASS
在原本使用Webpack情況下, 我們可以透過loader 將sass/scss轉譯成css 檔案, 但當我們改用Vite的時候, 我們就必須自己另外安裝css preprocessor
官網教學文件: https://vitejs.dev/guide/features.html#css-pre-processors
# .scss and .sass
npm add -D sass
# .less
npm add -D less
# .styl and .stylus
npm add -D stylusNote: 如果發現在安裝新版的sass後,發現map-get()語法出現錯誤時, 可參考這個解決方法
Sass map.get() doesn’t work. map-get() does. What gives?
主要在.sass/.scss 檔案內的最上方加上這一段
@use "sass:map";並將map-get()改成map.get() 即可
移除CSS import 路徑的prefix”~”
當import path 上有“~“, 例如: import “~/a/b/c”, 原本是要讓Webpack內的css-loade知道該路徑需要去node的相依模組內找到符合”/a/b/c”的檔案或模組.
官網說明文件: https://webpack.docschina.org/loaders/css-loader/#import
而Vite 已經不使用Webpack, 所以也就不會使用css loader來解析”~”, 因此可能會出現這樣的錯誤訊息
In vite it is simply @import 'npm_package/path/file.scss' without any extra prefix like ~.要解決這個問題只要將這個prefix”~” 移除即可
vite.config.js adjustment
大部分的設定都可以沿用vue.config.js
不過使用 Vite 的時候, Vite預設不會將打包的檔案分類, dist資料夾只會長這樣
// /dist/
/dist/
- /assets/ //All static files are put here
- index.html
- favicon.png如果需要做檔案分類的話, 可以在vite.config.js 加入”build“ 設定
// vite.config.js
build: {
...,
+ rollupOptions: {
+ output: {
+ chunkFileNames: 'js/[name]-[hash].js',
+ entryFileNames: 'js/[name]-[hash].js',
+ assetFileNames: ({ name }) => {
+ if (/\\.(gif|jpe?g|png|svg)$/.test(name ?? '')) {
+ return 'images/[name]-[hash][extname]';
+ }
+
+ if (/\\.css$/.test(name ?? '')) {
+ return 'css/[name]-[hash][extname]';
+ }
+
+ if (/\\.(woff|ttf|eot)$/.test(name ?? '')) {
+ return 'fonts/[name]-[hash][extname]';
+ }
+
+ // default value
+ // ref: <https://rollupjs.org/guide/en/#outputassetfilenames>
+ return '[name]-[hash][extname]';
+ },
+ },
+ },
},其他障礙排除
Stylelint 發生錯誤 “Unknown word CssSyntaxError”
解決方式: 安裝 “stylelint-config-recommended-vue“ 並在 “stylelintrc.js” 的extends 引用該套件
// stylelintrc.js
module.exports = {
...,
extends: [
...,
"stylelint-config-recommended-vue/scss",
],
...
}Unable to resolve the path to the module
解決方式: 在eslintrc.js內加入 moduleDirectory
module.exports = {
settings: {
'import/resolver': {
node: {
moduleDirectory: ['src/'],
},
},
},
}當用Jest 跑unit test cases時, 出現此錯誤“SyntaxError: Cannot use ‘import.meta’ outside a module”
解決方式:
- Install
babel-plugin-transform-import-meta: Replaceimport.meta.urlfor Node.js environments. - Install
babel-preset-vite: Replaceimport.meta.globfor Node.js environments.
// babel.config.js
module.exports = {
env: {
test: {
presets: ['babel-preset-vite'],
plugins: [
'babel-plugin-transform-import-meta',
]
}
}
}CLI Engine is not a constructor
解決方式: 更新eslint 與eslint-plugin-vue 版本到以下版本
參考來源: https://github.com/eslint/eslint/issues/15175#issuecomment-1016552619
"eslint": "^6.8.0",
"eslint-plugin-vue": "^6.2.2"無法建立WebSocket 連現時
修改vite.config.js 內websocket的proxy設定
'/ws': {
target: [URL],
ws: true, // Add "ws" property
},