你有沒有經(jīng)歷過這種場景項目里有個 utils 文件夾里面的 isMobile 函數(shù)有三四種實現(xiàn)有的用正則有的拿 navigator.userAgent 去判斷還有的是三年前從舊項目里直接 copy 過來的。當(dāng)你想抽個公共模塊統(tǒng)一一下時發(fā)現(xiàn)這些實現(xiàn)之間還有各種微妙的差異根本不敢隨便動。這種“重復(fù)造輪子”的混亂狀態(tài)我忍了很長時間最后下定決心干脆自己從零搭一套可復(fù)用的前端通用工具庫把常用的函數(shù)、組合式 API、通用組件都規(guī)范化讓以后的新項目能直接裝上用不用再到處翻歷史代碼。這篇文章我會基于 Vue3 JavaScript配合 Vite 的庫模式從 0 開始搭建這樣一個工具庫完整展示項目的目錄結(jié)構(gòu)、核心代碼實現(xiàn)、打包配置、單元測試和發(fā)布流程。全程用 JS 而不是 TypeScript主要照顧到團隊里很多工程還是純 JS 技術(shù)棧不想為了一個工具庫額外引入類型編譯成本。適合那些想把手頭零散的 utils 方法沉淀成正式 npm 包的開發(fā)者也適合想搞懂 Vite 庫模式到底怎么用的人。讀完你不僅能跑通整個流程還能避開我在實際搭建中踩過的幾個坑。1. 先想清楚通用工具庫究竟要解決誰的什么問題1.1 工具庫解決的是“重復(fù)成本”而非“炫技”很多同學(xué)一提到自建工具庫第一反應(yīng)是“我要把 lodash 重新寫一遍”其實不是這么回事。工具庫的核心價值是降低重復(fù)成本這個成本包括三部分寫代碼的時間、找代碼的時間、維護代碼的時間。我見過一個團隊內(nèi)部有三個不同的項目都寫了 formatDate 函數(shù)每個函數(shù)的輸出格式還不完全一樣有的支持傳入連字符有的只支持斜杠。后來產(chǎn)品要求統(tǒng)一日期展示格式負(fù)責(zé)的老兄花了整整一個下午去改三套實現(xiàn)改完還不敢保證邊界情況全部覆蓋。如果當(dāng)初有一個統(tǒng)一維護的工具函數(shù)這個問題就是改一個文件、發(fā)一個新版、所有項目升級依賴這么簡單。但自建工具庫也不是毫無成本你需要配置構(gòu)建、測試、文檔、發(fā)布還要持續(xù)維護。所以正確的姿勢是先判斷“值不值得做”。我的判斷標(biāo)準(zhǔn)很簡單只要存在一個函數(shù)或組件連續(xù)出現(xiàn)在三個以上項目里并且它們的行為基本一致就值得沉淀進工具庫。如果只是當(dāng)前項目一處用到就先忍住別抽等第二次需要時再抽也不遲。1.2 什么代碼適合放進通用工具庫適合放進通用工具庫的代碼有這幾個共同特征無業(yè)務(wù)上下文、依賴外部環(huán)境少、可以獨立測試、結(jié)果可預(yù)期。以純函數(shù)為例日期格式化、千分位轉(zhuǎn)換、URL 參數(shù)解析、uuid 生成都非常適合。組合式 API 方面useWindowSize、useLocalStorage、useEventListener 這類也是天然的工具庫素材。通用組件就更多了比如可定制的高亮文本、懶加載圖片、防重復(fù)點擊按鈕等。不適合的典型例子是封裝了特定后端接口的 request比如帶了某個接口的鑒權(quán)頭、綁定業(yè)務(wù)權(quán)限的指令、只服務(wù)于當(dāng)前頁面布局的巨型組件。這些代碼一旦脫離當(dāng)前業(yè)務(wù)環(huán)境就廢了硬塞進工具庫只會讓維護者為了抽象這些業(yè)務(wù)邏輯而頭疼。還有一個容易忽略的判斷維度團隊成員的使用習(xí)慣。如果你建了一個工具庫但其他項目的人根本不用那就是在自娛自樂。所以我在動手之前專門拉了一個清單把日常代碼里重復(fù)出現(xiàn)的小函數(shù)都列出來先統(tǒng)計使用頻率再決定首批放哪些工具。這一步看起來簡單實際決定了工具庫后續(xù)的活躍度。另外說一下為什么選 Vue3 JS 而不直接上 TS。我自己項目里有相當(dāng)一部分是遺留的 JS 代碼如果工具庫用 TS 寫雖然能提供類型聲明但構(gòu)建鏈路會復(fù)雜一截而且會讓不愿意碰 TS 的同事產(chǎn)生距離感。Vue3 的組合式 API 本身對 JS 的友好度很高很多邏輯根本不需要類型系統(tǒng)就能表達(dá)得很清晰。當(dāng)然如果你的團隊全員 TS那直接用 TS 寫會更好——工具庫的選型永遠(yuǎn)跟著團隊現(xiàn)狀走不是跟著技術(shù)潮流走。2. 工程化骨架用 Vite 的庫模式搭出可發(fā)布的包2.1 初始化項目與基礎(chǔ)依賴新建一個工具庫項目最省事的方式是用 Vite 的腳手架保留 Vue3 模板。我用的命令是這樣的npm create vitelatest my-utils -- --template vue模板帶上的 React 之類的東西都可以刪掉我們只需要一個干凈的 Vite Vue3 環(huán)境。因為這個工具庫不是業(yè)務(wù)應(yīng)用所以入口不再是 index.html而是一個倉庫入口文件這點后面會重點說。依賴安裝上除了 vue 和 vite我還會加這幾個運行時無關(guān)的工具npm install -D vitest vue/test-utils eslint prettier husky lint-staged這里稍微解釋一下為什么需要這些。vitest 用來跑單元測試因為它是 Vite 生態(tài)的測試框架可以復(fù)用同一個 vite.config不用單獨配一套vue/test-utils 是 Vue 組件測試的官方工具庫測組件必用eslint 和 prettier 統(tǒng)一代碼風(fēng)格husky 和 lint-staged 負(fù)責(zé)在提交前攔截不規(guī)范代碼。對一個公共工具庫來說質(zhì)量門禁是必須的因為代碼一旦發(fā)布出去被多個項目依賴任何低級錯誤都會被無限放大。2.2 Vite 的 lib 模式配置解析Vite 默認(rèn)構(gòu)建的是應(yīng)用會從 index.html 出發(fā)生成一堆靜態(tài)資源。工具庫要的是“庫模式”——從一個 JS 入口開始把內(nèi)容編譯成可被其他代碼 import 的包。配置核心就落在build.lib上。我最終的 vite.config.js 是這樣寫的import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], build: { lib: { entry: src/index.js, name: MyUtils, formats: [es, cjs, umd], fileName: (format) format es ? my-utils.esm.js : my-utils.${format}.js }, rollupOptions: { external: [vue], output: { globals: { vue: Vue } } } }, test: { environment: jsdom } })這里面的關(guān)鍵點值得好好說說。entry指向的是包入口工具庫所有對外暴露的能力都從這個文件導(dǎo)出。formats我選了 es、cjs、umd 三種ESM 適合現(xiàn)代打包器可以觸發(fā) tree-shakingCJS 是為了兼容舊版 Node 環(huán)境和老式構(gòu)建器UMD 則是給那些直接在 script 標(biāo)簽里引用的人用的雖然現(xiàn)在已經(jīng)很少見但加上總沒壞處。rollupOptions.external: [vue]是一個特別重要的配置。它告訴 Vite“vue 這個依賴不要打包進我的產(chǎn)物里?！币驗楣ぞ邘炖锏慕M件、組合式 API 都依賴 Vue但 Vue 應(yīng)該由使用方項目提供而不是工具庫重復(fù)打包一份。如果這里不排除發(fā)布出去的包體積會大很多而且可能導(dǎo)致使用方項目里同時存在兩份 Vue 實例觸發(fā)各種奇奇怪怪的問題。這點我在后面第 6 部分還會專門強調(diào)。2.3 目錄結(jié)構(gòu)設(shè)計JS 工具、組合式函數(shù)、組件分開維護工具庫不是把所有代碼堆在一個文件里就完事目錄結(jié)構(gòu)直接決定了后續(xù)的可維護性。我采用的是一套簡單清晰的分層模式my-utils/ ├── src/ │ ├── index.js # 入口統(tǒng)一導(dǎo)出 │ ├── funcs/ # 純函數(shù)工具 │ │ ├── formatDate.js │ │ ├── debounce.js │ │ └── ... │ ├── composables/ # 組合式 API │ │ ├── useWindowSize.js │ │ ├── useLocalStorage.js │ │ └── ... │ └── components/ # 通用 Vue 組件 │ ├── HighlightText/ │ │ ├── index.js │ │ └── HighlightText.vue │ └── ... ├── test/ # Vitest 測試用例 ├── dist/ # 構(gòu)建產(chǎn)物gitignore ├── package.json ├── vite.config.js └── ...為什么把純函數(shù)、組合式 API、組件分成三個目錄因為它們的用法和構(gòu)建路徑完全不同。純函數(shù)是普通 JS 模塊可以直接被任何環(huán)境加載組合式 API 依賴 Vue 的運行時但不需要渲染組件則必須有 Vue 的渲染器配合。分開后后續(xù)做按需引入時非常方便使用者可以精確地只加載一個模塊。入口文件src/index.js的作用是把所有能力匯總到一處方便全量引用。同時我也在 package.json 里配好了子路徑導(dǎo)出讓使用者既能import { debounce } from my-utils全量引入也能import debounce from my-utils/funcs/debounce精準(zhǔn)引入這其實就是按需加載的另一種手段后面詳細(xì)講。這樣一個骨架搭完你就有了一個干凈的起點。接下來最核心的事情就是往里面填充真正有用的代碼。3. 通用函數(shù)、組合式 API、組件三類能力的實現(xiàn)與設(shè)計思路3.1 純函數(shù)以 formatDate 和 debounce 為例純函數(shù)是工具庫的基本盤。寫這些函數(shù)的核心原則是輸入可預(yù)期、輸出穩(wěn)定、不做意外的事。我拿兩個最常見的例子展開。第一個是formatDate。很多項目都用 date-fns 或 dayjs但為了一個兩個格式化的需求去引整個庫其實有點重。自己寫一個針對常用格式的輕量函數(shù)就夠了// src/funcs/formatDate.js export function formatDate(date, fmt YYYY-MM-DD HH:mm:ss) { const d date instanceof Date ? date : new Date(date) if (Number.isNaN(d.getTime())) { throw new TypeError(formatDate received an invalid date) } const pad (n) String(n).padStart(2, 0) const map { YYYY: d.getFullYear(), MM: pad(d.getMonth() 1), DD: pad(d.getDate()), HH: pad(d.getHours()), mm: pad(d.getMinutes()), ss: pad(d.getSeconds()) } return fmt.replace(/YYYY|MM|DD|HH|mm|ss/g, (match) String(map[match])) }我特意沒有做很復(fù)雜的令牌解析只覆蓋了最常見的年月日時分秒為什么這么克制因為工具庫的代碼要盡可能容易被后續(xù)的人讀懂功能越多、邊界情況越多潛在的風(fēng)險就越大。當(dāng)實際需求超出這個范圍時直接按 dayjs 或者 date-fns 更合理不要試圖自己架一個完整的日期引擎。一個容易被忽略的細(xì)節(jié)入?yún)⒍x成date instanceof Date ? date : new Date(date)。這樣字符串日期、時間戳都能兼容并且當(dāng)傳入非法值時會顯式拋錯而不是返回一個又難看又難排查的NaN/NaN/NaN。顯式拋錯是工具代碼里值得推崇的做法——寧可讓調(diào)用方在開發(fā)階段就發(fā)現(xiàn)錯誤也不要把錯誤吞掉。第二個例子是debounce這個函數(shù)幾乎每個項目都自己寫過一版但很多版本在“取消”和“立即執(zhí)行”這兩個能力上是缺失的。工具庫里的 debounce 應(yīng)該更完整// src/funcs/debounce.js export function debounce(fn, wait 300, immediate false) { if (typeof fn ! function) { throw new TypeError(expected a function as first argument) } let timer null let result null const debounced function (...args) { return new Promise((resolve) { const later () { timer null if (!immediate) { result fn.apply(this, args) resolve(result) } } const callNow immediate !timer clearTimeout(timer) timer setTimeout(later, wait) if (callNow) { result fn.apply(this, args) resolve(result) } }) } debounced.cancel () { clearTimeout(timer) timer null } return debounced }這里有兩個設(shè)計點是我從實際項目里總結(jié)出來的。第一用 Promise 包一層讓調(diào)用方可以用await debounced()拿到函數(shù)返回結(jié)果這對手寫版 debounce 來說是不常見的但實際在某些需要等待結(jié)果入庫的場景特別好用。第二保留.cancel方法這樣在組件卸載時能優(yōu)雅地清理掉還未觸發(fā)的任務(wù)避免在異步回調(diào)里觸發(fā)對已卸載組件的操作。3.2 組合式 API封裝一個 useWindowSizeVue3 的組合式 API 非常適合做工具庫因為它能把響應(yīng)式狀態(tài)、副作用生命周期都管理起來。我用useWindowSize來示范一個標(biāo)準(zhǔn)寫法// src/composables/useWindowSize.js import { ref, onMounted, onUnmounted } from vue export function useWindowSize() { const width ref(window.innerWidth) const height ref(window.innerHeight) const update () { width.value window.innerWidth height.value window.innerHeight } onMounted(() { window.addEventListener(resize, update) }) onUnmounted(() { window.removeEventListener(resize, update) }) return { width, height } }為什么用ref而不是reactive因為返回的是一個雙成員對象用 ref 包裹后使用方可以優(yōu)雅地解構(gòu)const { width, height } useWindowSize()同時這兩個值在模板里可以直接渲染不會丟失響應(yīng)性。而如果用 reactive 包裝解構(gòu)后響應(yīng)性就斷了。監(jiān)聽事件一定要放在onMounted里嗎不一定如果你的工具庫只會在組件實例中調(diào)用那么 onMounted 是安全的。但如果你希望這個函數(shù)也能在普通 JS 環(huán)境沒有組件上下文下使用那就需要做一些兼容處理比如直接用const update () {...}然后立即初始化再返回一個手動銷毀的方法。我這里的寫法是為絕大多數(shù) Vue 單文件組件場景設(shè)計的簡單可靠。需要額外說明的是組件的onUnmounted保證了 resize 監(jiān)聽器在組件銷毀時被移除這能避免大多數(shù)內(nèi)存泄漏問題。再多說一點工具型的 composable 最重要的是“副作用可控”。類似useWindowSize這種監(jiān)聽一個全局事件就必須在合適時機解綁絕不能讓使用方背著內(nèi)存泄漏的債。3.3 通用組件從最簡單的高亮文本組件開始通用組件是工具庫里比較容易“膨脹”的部分因為 UI 設(shè)計千差萬別強行做成通用往往兩頭不討好。我建議從沒有視覺綁定的功能型組件開始比如高亮文本。它負(fù)責(zé)接收關(guān)鍵詞把匹配到的片段用mark或其他標(biāo)簽包起來至于樣式直接由使用方的項目控制。用 Vue3 的 SFC 和 JS 實現(xiàn)如下!-- src/components/HighlightText/HighlightText.vue -- template span classmy-utils-highlight-text template v-for(part, index) in parts :keyindex {{ part.text }}slot v-ifpart.match namehighlight :partpart{{ part.text }}/slot /template /span /template script setup import { computed } from vue const props defineProps({ text: { type: String, required: true }, keyword: { type: String, default: }, caseSensitive: { type: Boolean, default: false } }) const parts computed(() { if (!props.keyword || !props.text) { return [{ text: props.text || , match: false }] } const flags props.caseSensitive ? g : gi const regex new RegExp((${escapeRegExp(props.keyword)}), flags) return props.text .split(regex) .filter((segment) segment ! undefined) .map((segment, index) ({ text: segment, match: regex.test(segment), index })) }) function escapeRegExp(str) { return str.replace(/[.*?^${}()|[\]\\]/g, \\$) } /script組件可以配合插件式注冊實現(xiàn)全量引入// src/components/HighlightText/index.js import HighlightText from ./HighlightText.vue export default HighlightText然后在主入口里注冊// src/index.js export { default as HighlightText } from ./components/HighlightText/index.js組件本身不綁定任何樣式由使用方項目用樣式覆蓋這是保持通用性的關(guān)鍵。如果你在組件里寫死了背景色和字體到每個項目里都會有人抱怨“顏色對不上”。這里的關(guān)鍵詞匹配我特意用正則做了轉(zhuǎn)義避免用戶輸入*或.等正則特殊字符導(dǎo)致匹配行為異常。高亮文本組件規(guī)模不大但它演示了工具組件最基本的設(shè)計思路props 傳入數(shù)據(jù)、不依賴業(yè)務(wù)狀態(tài)、支持插槽做擴展、無內(nèi)置樣式。后續(xù)要擴展其他組件時都可以參考這個模式。4. 質(zhì)量保障ESLint Prettier Vitest 讓工具庫少踩坑4.1 ESLint 與 Prettier 配置要點工具庫代碼會被很多人依賴代碼風(fēng)格不統(tǒng)一會直接導(dǎo)致合并沖突和 review 效率低下。我在項目里集成了 ESLint 和 Prettier配置比較簡單但夠用。// .eslintrc.cjs module.exports { root: true, env: { browser: true, node: true, es2022: true }, extends: [ eslint:recommended, plugin:vue/vue3-essential, prettier ], parserOptions: { ecmaVersion: 2022, sourceType: module }, rules: { vue/multi-word-component-names: off } }vue/multi-word-component-names這個規(guī)則默認(rèn)要求組件名必須是多個單詞但對于工具庫來說很多通用組件就是HighlightText、DebounceButton這種兩詞名字也有個別像Button這種基礎(chǔ)組件所以關(guān)掉比較省心。Prettier 簡單配置一個.prettierrc{ semi: false, singleQuote: true, trailingComma: none, printWidth: 100 }因為主要是 JS 文件行寬設(shè) 100 足夠。把 ESLint、Prettier、Vite 同時跑通的好處是代碼風(fēng)格不再需要人工 review機器幫你兜底。4.2 給工具庫補上單元測試Vitest工具庫是純邏輯居多不測一下說不過去。Vitest 和 Vite 深度集成跑測試直接用vitest命令就行。我寫幾個典型測試// test/formatDate.test.js import { describe, it, expect } from vitest import { formatDate } from ../src/funcs/formatDate describe(formatDate, () { it(formats date correctly, () { const date new Date(2024, 0, 15, 9, 30, 45) expect(formatDate(date)).toBe(2024-01-15 09:30:45) }) it(throws on invalid date, () { expect(() formatDate(not-a-date)).toThrow(TypeError) }) })debounce 的測試需要依賴 fake timersVitest 同樣支持// test/debounce.test.js import { describe, it, expect, vi } from vitest import { debounce } from ../src/funcs/debounce describe(debounce, () { it(waits until wait time passes before invoking, () { vi.useFakeTimers() const fn vi.fn() const debounced debounce(fn, 200) debounced() vi.advanceTimersByTime(100) expect(fn).not.toHaveBeenCalled() vi.advanceTimersByTime(100) expect(fn).toHaveBeenCalledTimes(1) vi.useRealTimers() }) })組合式 API 的測試稍微復(fù)雜一點需要提供一個宿主環(huán)境。Vitest 開了environment: jsdom后我們可以用vue/test-utils掛載一個小組件來驗證// test/useWindowSize.test.js import { describe, it, expect, vi } from vitest import { mount } from vue/test-utils import { defineComponent, h } from vue import { useWindowSize } from ../src/composables/useWindowSize describe(useWindowSize, () { it(returns window dimensions, async () { const Comp defineComponent({ setup() { const size useWindowSize() return () h(div, ${size.width.value}x${size.height.value}) } }) window.innerWidth 1024 window.innerHeight 768 const wrapper mount(Comp) expect(wrapper.text()).toBe(1024x768) window.innerWidth 1280 window.dispatchEvent(new Event(resize)) await wrapper.vm.$nextTick() expect(wrapper.text()).toBe(1280x768) wrapper.unmount() }) })這種測試的意義是保證核心函數(shù)的行為回歸可控。工具庫一旦發(fā)布任何一次升級都可能影響很多項目沒有測試誰敢隨便升版本所以我個人的建議是工具庫里的每個函數(shù)至少一個主流程測試加一個邊界測試每個 composable 至少測掛載和銷毀組件至少測 props 渲染。4.3 lint-staged husky 攔截不規(guī)范的提交有了 ESLint 和測試還需要把它們卡在提交前否則總有人跳過檢查。簡單搭一個 husky 鉤子npx husky init然后配置lint-staged在 package.json 里{ lint-staged: { *.{js,vue}: [eslint --fix, prettier --write] } }同時.husky/pre-commit里寫npx lint-staged這樣每次提交只會檢查暫存區(qū)里的文件速度很快也不會逼著大家把所有測試跑一遍。更嚴(yán)謹(jǐn)點的團隊可以在 pre-push 階段跑全量測試但工具庫代碼量不大所以我在 commit 前直接跑了npm test npm run lint也行。質(zhì)量門禁的意義不在于設(shè)置多少關(guān)卡而在于讓團隊所有人都保持一致的習(xí)慣。5. 打包與發(fā)布從本地工具庫到 npm 公共包5.1 多格式產(chǎn)物與 Tree ShakingVite 庫模式在build后會在 dist 目錄下生成三個文件my-utils.esm.js、my-utils.cjs.js、my-utils.umd.js。ESM 文件內(nèi)部使用 ES Module 語法現(xiàn)代打包器Vite、webpack 5、Rollup在解析 import 時可以靜態(tài)分析導(dǎo)出成員從而剔除未使用的代碼這就是 tree-shaking 的基礎(chǔ)。要讓 tree-shaking 真正生效package.json 里必須明確sideEffects: false意思是這個包里的模塊都沒有副作用。但組件文件可能包含樣式副作用所以如果你有 CSS需要單獨處理。我的做法是把組件樣式內(nèi)聯(lián)到組件里用style scoped這樣 Vite 在編譯后會把 CSS 抽離成單獨的 CSS 文件在 package.json 里通過sideEffects指定 CSS 文件有副作用其他模塊沒有。目前我們先不引入 CSS保持sideEffects: false是最省心的。5.2 package.json 的關(guān)鍵字段構(gòu)建產(chǎn)物出來后發(fā)布配置是重中之重。我最終的 package.json 關(guān)鍵字段長這樣{ name: my-utils, version: 0.1.0, description: A collection of Vue3 JS utilities, composables and components, type: module, main: ./dist/my-utils.cjs.js, module: ./dist/my-utils.esm.js, unpkg: ./dist/my-utils.umd.js, exports: { .: { import: ./dist/my-utils.esm.js, require: ./dist/my-utils.cjs.js }, ./funcs/*: ./dist/funcs/*.js, ./composables/*: ./dist/composables/*.js, ./components/*: ./dist/components/*.js }, files: [dist, README.md], peerDependencies: { vue: 3.2.0 }, sideEffects: false, scripts: { build: vite build, test: vitest run, lint: eslint src test --fix } }幾個字段解釋一下。main指向 CJS 產(chǎn)物是為了兼容還沒有切換到 ESM 的舊 Node 環(huán)境。module指向 ESM 產(chǎn)物現(xiàn)代打包器會優(yōu)先讀取。exports字段是 Node.js 12 和現(xiàn)代打包器的新標(biāo)準(zhǔn)它比 main/module 更精細(xì)能限制外部訪問包內(nèi)未聲明的路徑防止別人import my-utils/src/xxx這種奇怪的引用方式。files決定發(fā)布時哪些文件會被打進 npm 包這里只包含 dist 和 README能有效避免把源碼、測試文件全部發(fā)布出去既縮小包體積也避免暴露未編譯的內(nèi)部細(xì)節(jié)。peerDependencies用來聲明這個包依賴的宿主版本——Vue 3.2 及以上但不會把 Vue 安裝進來。在發(fā)布前建議先本地驗證一下npm pack這會生成my-utils-0.1.0.tgz你可以解開看看里面有什么再或者用一個臨時項目npm install /path/to/my-utils-0.1.0.tgz實際引用一下確保發(fā)布到 npm 后不會出現(xiàn)“裝回來發(fā)現(xiàn)缺文件”的尷尬。5.3 版本號與更新日志別讓發(fā)布變成災(zāi)難工具庫的版本管理我強烈建議走語義化版本SemVer也就是MAJOR.MINOR.PATCH。新增一個向后兼容的函數(shù)升 MINOR修復(fù)原有函數(shù)的 bug升 PATCH如果你改了函數(shù)入?yún)?、調(diào)整了組件 props 的必填項這類破壞性變化一定要升 MAJOR。配合 conventional commits可以在每次提交時自動生成 CHANGELOG。比如feat: add useLocalStorage會被識別為 feature 更新fix: correct formatDate timezone offset會被識別為 bug 修復(fù)。我在項目里用了standard-version這個工具來根據(jù)提交記錄自動生成版本號和 changelog執(zhí)行npx standard-version就會自動修改 version、生成 CHANGELOG.md、打上 git tag非常省事。不過版本生成的粒度還是要自己控制。工具庫的發(fā)布頻率不宜太高我一般會在一次功能迭代完成后集中發(fā)布一版而不是每次 commit 都發(fā)。多個項目共用一個工具庫的好處也體現(xiàn)在這里——只有你的版本規(guī)劃做得足夠清晰下游項目才能放心地跟進升級。6. 實戰(zhàn)中繞不開的坑記住了能省下半天時間6.1 Vue 外部化后別忘了開發(fā)依賴?yán)锏?vue前面說了打包時要把 Vue 設(shè)為 external但很多新手會掉進另一個坑既然 vue 是 peerDependencies是不是項目里就不用裝 vue 了不是的。你本地開發(fā)工具庫時仍然需要 vue 作為 devDependency因為組件和測試都要實際運行。peerDependencies 解決的是“使用方要自己裝 vue”而 devDependencies 解決的是“你在開發(fā)這個庫時需要 vue 可用”。我見過一個例子某位同事把 vue 從 devDependencies 里刪掉認(rèn)為發(fā)布時會自動帶上結(jié)果本地跑測試直接報“Cannot find module ‘vue’”。正確的習(xí)慣是vue 同時出現(xiàn)在 peerDependencies 和 devDependencies 里peer 里寫寬松范圍如3.2.0dev 里寫一個明確的版本保證本地開發(fā)環(huán)境可控。6.2 Tree Shaking 對組件并沒有想象中那么靈組件跟純函數(shù)不一樣。如果你在主入口 index.js 里一次性導(dǎo)出了 10 個組件然后使用方通過import { Button } from my-utils這樣的方式按需引用現(xiàn)代打包器確實可以通過 tree-shaking 把沒用到的組件代碼丟掉。但這里有個前提組件內(nèi)部不能被任何模塊級副作用觸發(fā)比如組件文件頂部直接插入全局 CSS 或執(zhí)行console.log。更讓人頭疼的是如果使用方項目用 webpack 4 這類對 tree-shaking 支持不完善的老構(gòu)建器一個入口導(dǎo)出很多組件反而可能導(dǎo)致全部被打進 bundle 里。這時候你就需要子路徑導(dǎo)出讓使用方可以import Button from my-utils/components/Button這樣的精確引用繞開 tree-shaking 的機制限制。這也是我在 package.json 里配置 exports 子路徑的初衷——為老舊項目留一條后路。6.3 發(fā)布前務(wù)必先本地聯(lián)調(diào)最好用 npm link 或 yalc我最后一次發(fā)布的教訓(xùn)是“發(fā)布一時爽打完臉就腫”。那次我更新了一個組件里的 prop 默認(rèn)值本地構(gòu)建和測試都通過了直接npm publish結(jié)果有個項目升級后組件的樣式全亂了。原因是我漏改了另一處相關(guān)代碼但本地沒有實際業(yè)務(wù)場景測試也沒有覆蓋到所有 CSS 組合。從那以后我養(yǎng)成了發(fā)布前先用npm link或者yalc把包鏈接到實際項目里做冒煙驗證的習(xí)慣。npm link的用法很簡單在工具庫目錄里執(zhí)行npm link再在目標(biāo)項目里執(zhí)行npm link my-utils這樣目標(biāo)項目引用的就是本地源碼產(chǎn)物改動后的效果能立即看到。但 npm link 會改變 node_modules 的符號鏈接結(jié)構(gòu)偶爾會觸發(fā) vite 緩存問題所以我個人更喜歡 yalc——它會把本地發(fā)布文件“推”到目標(biāo)項目的 node_modules 里更接近真實依賴情況也不會因為符號鏈接導(dǎo)致某些工具無法解析。說到底工具庫開發(fā)的完整閉環(huán)是“編碼 - 測試 - 構(gòu)建 - 本地聯(lián)調(diào) - 發(fā)布”。前四步走得越扎實最后一步就越穩(wěn)。每當(dāng)我偷懶跳過本地聯(lián)調(diào)時幾乎都會在下一次發(fā)布后收到一個“有問題”的反饋。所以現(xiàn)在我的出包流程里npm pack和本地冒煙這步已經(jīng)成了肌肉記憶。從我這次搭建工具庫的經(jīng)歷來看最耗時間的不是寫那幾十個函數(shù)而是讓整個項目變得干凈、可信、可維護的過程。工具庫的本質(zhì)是給未來的自己和其他項目“預(yù)寫”代碼如果你的包發(fā)布一次就要讓下游項目改一次配置那這個工具庫就失去了意義。如果你也打算動手我的建議是從一個最小的函數(shù)庫開始先跑通打包發(fā)布流程再逐步加入組合式 API 和組件別一開始就想面面俱到。最后再分享一個小技巧每次構(gòu)建之后進 dist 目錄隨便打開一個產(chǎn)物文件看看里面有沒有意外的殘留代碼比如過期的注釋、調(diào)試用的 console 語句——有一次我就在產(chǎn)物里發(fā)現(xiàn)了一段被誤加到純函數(shù)里的 console.warn還好發(fā)的是預(yù)發(fā)布版本沒有影響線上項目。這種細(xì)節(jié)點滴積累起來就是工具庫和其他人的隨手分享之間最大的區(qū)別。