在 esbuild 專案中整合 Alpine.js 的完整指南
更新日期： 2025 年 1 月 7 日
本文為 留言評分功能 系列教學，第 4 篇：
- 使用 Django + Tailwind + Alpine.js 實作「五顆星評分」功能教學
- Django validators 驗證器完整教學
- Django PositiveSmallIntegerField 新手指南
- 在 esbuild 專案中整合 Alpine.js 的完整指南 👈 所在位置
- 使用 Alpine.js 建立星星評分表單 — 新手指南
- 深入理解 Alpine.js 中的 template 標籤使用指南
- Django 網站如何新增「星星評分」功能 — 後端接收邏輯
- Django 表單：如何讓使用者選擇性提交星星評分與留言
- Django 如何限制同一使用者只能對同一服務留言一次？
- Django 留言軟刪除邏輯｜程式碼解析
- Django 計算評分摘要教學 — 使用 ORM 進行星等統計
- Python Django 使用 annotate、aggregate 統計教學
- 使用 Alpine.js 實作星級評分分佈 – 詳細教學
- Alpine.js 與 Tailwind CSS 動態樣式解析：為什麼有些樣式無法生效？
- Django 中使用 annotate() 與 Avg() 進行平均評分計算
本教學將引導新手如何在使用 esbuild 作為打包工具的專案中，成功整合 Alpine.js。
Alpine.js 是一個輕量且直觀的 JavaScript 框架，適用於增強前端互動性，特別適合小型專案或需要簡單互動行為的網頁。
本指南假設你的專案已經安裝了 htmx 和 vue，並希望新增 Alpine.js 以擴展前端互動功能。
我們將逐步介紹如何安裝、導入並測試 Alpine.js 是否成功運作。
什麼是 Alpine.js？
Alpine.js 是一個簡潔的 JavaScript 框架，專注於前端互動行為，特別適用於：
- 即時顯示或隱藏元素
- 表單處理與驗證
- 動態 UI 交互，例如星星評分、模態框
- 無需建立完整的 SPA (單頁應用程式)
它的語法受到 Vue.js 的啟發，但更加簡潔且易於整合。
安裝 Alpine.js
要在你的 esbuild 專案中使用 Alpine.js，請按照以下步驟進行安裝。
打開終端機並執行安裝指令
npm install alpinejs --save安裝成功後的確認
package.json檔案中應該出現以下內容：
"dependencies": {
"alpinejs": "^3.x.x"
}- 這表示
alpinejs已成功加入你的專案依賴。
導入並初始化 Alpine.js
接下來，你需要在 app.js 中導入並初始化 Alpine.js，以便前端可以正常使用它的功能。
編輯 app.js 並新增以下程式碼：
import Alpine from 'alpinejs';
// 將 Alpine.js 綁定到全域物件
window.Alpine = Alpine;
Alpine.start();這段程式碼的作用
import Alpine from 'alpinejs'：將 Alpine.js 模組導入到你的專案中。window.Alpine = Alpine：將 Alpine.js 綁定到全域物件，方便在瀏覽器開發者工具中進行測試與偵錯。Alpine.start()：初始化 Alpine.js，使其能夠作用於 HTML 元素。
設定 esbuild 打包
確保你的 esbuild 設定正確處理 JavaScript 模組，這樣才能順利打包並載入 Alpine.js。
esbuild.config.js 基本範例
require('esbuild').build({
entryPoints: ['src/app.js'],
bundle: true,
outfile: 'static/scripts/app.js',
minify: true,
watch: process.argv.includes('--watch'),
}).catch(() => process.exit(1));
指令說明
entryPoints：指定要打包的主程式入口。bundle：將所有依賴合併到一個檔案中。outfile：輸出的檔案路徑。minify：最小化檔案以減少檔案大小。watch：監聽檔案變更並自動重新打包。
執行打包並測試
進行打包
執行以下指令以使用 esbuild 進行打包：
npm run build或開啟 自動監聽模式（適用於開發階段）：
npm run dev確認打包成功
- 在專案的
/static/scripts/app.js中應該能看到包含 Alpine.js 相關的程式碼。 - 若有使用版本控制工具 (
git) 建議忽略打包後的檔案：
# .gitignore
static/scripts/app.js前端測試 Alpine.js 是否正常運作
在 HTML 中加入測試範例
打開你的 HTML 檔案，並加入以下程式碼以測試 Alpine.js 是否正常運作。
<!DOCTYPE html>
<html lang="zh-Hant">
<head>
<meta charset="UTF-8">
<title>Alpine.js 測試</title>
<script src="/static/scripts/app.js" defer></script>
</head>
<body>
<div x-data="{ count: 0 }" class="text-center">
<p class="text-xl">計數器: <span x-text="count"></span></p>
<button @click="count++" class="px-4 py-2 bg-blue-500 text-white rounded">增加</button>
<button @click="count--" class="px-4 py-2 bg-red-500 text-white rounded">減少</button>
</div>
</body>
</html>
開啟瀏覽器並測試
- 使用
npm run dev啟動伺服器，打開你的專案。 - 點擊「增加」與「減少」按鈕，確認計數器是否正常運作。
常見錯誤與除錯方法
無法找到 Alpine.js
- 確認你的
app.js是否有正確導入alpinejs。 - 檢查
/static/scripts/app.js是否存在並且包含Alpine.js相關程式碼。
JavaScript 未正確執行
- 確保你的
<script>標籤有使用defer屬性，以確保 DOM 載入後才執行 JavaScript。
變數無法即時更新
- Alpine.js 使用的是響應式資料綁定，請確認是否使用
x-data和x-text正確綁定。
總結
透過本篇教學，你已學會如何將 Alpine.js 整合進你的 esbuild 專案中，並完成以下步驟：
- 安裝 Alpine.js
- 導入並初始化 Alpine.js
- 設定 esbuild 打包器
- 打包並測試
- 常見錯誤排除
現在你已經成功將 Alpine.js 整合到專案中了！🎉