歷經 30 天的連續開發，這款以紀錄日常美好為核心的互動網頁——《微光採集瓶》，終於在今天正式完成部署並公開上線！

在這最後一天，我將記錄如何透過 GitHub Pages，將 Vue + Vite 專案發布至雲端靜態託管平台，並完整回顧這 30 天實作出的核心功能、互動細節與技術收穫。

專案線上連結

• 線上體驗網址： https://yi5210.github.io/quiet-wonders/

小提醒： 本專案特別針對行動裝置進行直向螢幕與觸控操作的優化，推薦使用手機瀏覽器開啟，也可以將網頁加入主畫面，獲得更接近獨立應用程式的使用體驗。

一、部署流程紀錄（GitHub Pages）

1. 設定 vite.config.js 的 base 路徑

GitHub Pages 的專案網站通常會使用 https://<username>.github.io/<repo-name>/ 這樣的網址格式。由於網站並非部署在網域根目錄，如果沒有正確設定 Vite 的 base，編譯後的資源可能會指向錯誤的路徑，導致頁面出現空白或資源載入失敗的問題。

因此，需要在 vite.config.js 中設定對應的 GitHub Repository 名稱：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  base: '/quiet-wonders/',
  plugins: [vue()],
})

這裡的 base 設定是部署至 GitHub Pages 專案網站的關鍵，必須對應 Repository 的名稱，才能確保編譯後的資源引用路徑正確。

先前為了透過 ngrok 進行外部連線測試，我曾在 Vite 設定中加入 host、port 與 allowedHosts 等開發伺服器參數。由於這些設定並非部署至 GitHub Pages 的必要條件，因此在正式部署的設定範例中將它們移除，讓設定檔保持簡潔。

2. 使用 gh-pages 工具自動化發布

接著，利用 gh-pages 套件將 Vite 編譯完成的 dist 目錄推送至 GitHub 遠端的 gh-pages 分支。

首先，在專案終端機執行以下指令：

# 1. 執行 Vite 生產環境編譯打包，產生 dist 目錄
npm run build

# 2. 將 dist 目錄推送到遠端的 gh-pages 分支
npx gh-pages -d dist

當終端機出現 Published 訊息時，即代表發布工具已成功將編譯後的檔案推送至 GitHub 遠端分支。

3. 設定 GitHub Pages 與排除載入問題

完成推送後，前往 GitHub Repository 的 Settings → Pages，將 Build and deployment 的 Branch 設定為 gh-pages，資料夾選擇 /(root)。

儲存設定後，GitHub Pages 就會以該分支中的檔案作為網站內容。

如果部署完成後首次開啟網站時出現空白畫面，可以先透過瀏覽器開發者工具檢查是否有資源載入失敗或路徑錯誤的訊息。如果確認是舊版資源快取造成的問題，再嘗試清除快取並強制重新載入，或使用無痕模式重新開啟網站。

至此，《微光採集瓶》就正式完成部署，從本機開發環境走向可以公開瀏覽的線上網站。

二、專案完整功能

整個專案從「首頁沉浸導引」、「日常採集防呆」、「心情光譜自訂」、「微光檢索互動」到「月底色卡儀式」，串連成一套完整的日常紀錄體驗。

1. 首頁導覽：從日常進入微光世界

首頁透過三步簡單的導引文字——寫下一件小事、選一個心情顏色、看著瓶子被點亮，引導使用者暫時放下整天的疲憊，回憶並紀錄當天發生的美好小事。

完成導引後，點擊按鈕即可順暢進入主採集介面，讓使用者在開始紀錄前，先建立一個屬於自己的小小儀式。

2. 採集頁面與光珠入瓶動畫

進入主畫面後，中央呈現具有透明質感的採集瓶與木塞結構。

使用者可以在輸入框中寫下當日的一件小事，文字上限為 20 字，再挑選代表當下心情的顏色。點擊「放入這道微光」後，光珠便會伴隨掉落動畫落入瓶底堆疊，同時帶動瓶身發出短暫的微光。

透過動畫與視覺回饋，讓原本單純的文字輸入，轉化成看得見的收藏過程。

3. 每日採集限制：避免重複放入

為了實踐「每天輕鬆採集一道美好」的設計理念，系統限制使用者每天只能手動採集一次。

當日完成採集後，按鈕會自動切換為停用狀態，顯示「今日微光已入瓶」，輸入框也會同步鎖定，並顯示「今天的美好已安放，明天見～」，避免同一天內重複新增手動光珠。

這項機制除了避免重複紀錄，也希望讓每日採集成為輕鬆而不帶壓力的小習慣。

4. 心情調色盤與標籤自訂

介面提供四種經過調整的柔和情境色彩，分別代表不同的心情：

• 平靜： 藍色 #8db3d4
• 喜悅： 黃色 #e6c683
• 溫柔： 粉色 #d7a9b8
• 安心： 綠色 #9bb89f

點擊「✎ 自訂名稱」後，系統會開啟全域設定視窗，讓使用者自由修改四種顏色所代表的意涵。

自訂名稱會同步儲存至 localStorage，並套用於後續的心情標籤與月度色卡，讓每個顏色都能擁有更貼近使用者個人感受的意義。

5. 時光檢索與光珠發光互動

隨著日子推進，瓶內會逐漸累積不同日期的微光。使用者可以透過中央的日期檢索列，選擇想回顧的特定日期。

• 聚焦當日微光： 符合日期的光珠會放大並呈現發光效果，讓使用者更容易辨識。
• 淡化其他日期： 其他光珠會自動套用灰階與淡化效果，降低視覺干擾。
• 恢復完整畫面： 點擊「重設」即可清除日期篩選，恢復瓶中所有光珠的原始顯示狀態。

透過這些互動，使用者不只能累積紀錄，也能更直覺地找到特定日子的回憶。

6. 點擊光珠檢視、當日編輯與撤回

直接點擊瓶中的任一顆光珠，都會開啟獨立的資訊視窗，依照紀錄類型提供不同的操作方式。

• 當日放入的光珠： 如果文字打錯或想調整心情，可以使用「編輯」修改內容，也可以透過「撤回」將光珠移出瓶子。
• 過往日期的光珠： 採用唯讀保護模式，無法直接修改或撤回，視窗下方會提示「昔日回憶已無法撤回」。
• 系統自動補漏的白色光珠： 如果有幾天沒有開啟網頁，系統會依照補漏規則建立留白光珠，並提示「留白也是很棒的一天，回想這天發生了什麼快樂的事呢？」。

透過不同的操作限制，讓當日紀錄保有調整彈性，同時也讓過往的回憶維持穩定。

7. 隔月首日補領橫幅

如果進入新月份的第一天時，上個月仍有尚未完成封存的微光紀錄，畫面上方就會自動顯示「新月份開始了！上月記憶已總結」的補領橫幅。

使用者可以點擊橫幅中的按鈕，開啟上個月的微光色卡，進行回顧與補封存。

這項機制是為了處理使用者沒有在月底當天完成封存的情況，避免因為錯過特定日期，就無法回顧前一個月累積的生活紀錄。

8. 月底封存儀式與極光色卡生成

每個月的最後一天，在符合封存條件時，系統會觸發專屬的月底封存儀式。

動畫開始後，木塞彈開，瓶中的光珠一顆顆向上飛出瓶口，隨後凝聚成專屬的「月度微光色卡」。

色卡背景透過多重徑向漸層，依據當月不同心情顏色的比例動態混合，生成獨一無二的極光視覺效果，並標示各項心情的百分比。

原本散落在每一天的紀錄，就這樣被整理成一張代表整個月份的色彩印記，讓使用者可以用不同的方式回顧自己的生活。

9. 色卡圖片下載與時光相簿

月度色卡生成後，除了能直接在網頁中欣賞，也提供下載與珍藏功能，讓每個月的紀錄都能被保存下來。

• 下載色卡： 透過 html-to-image 套件，將生成的極光色卡轉換為 PNG 圖片，方便使用者保存至本機。
• 珍藏至時光相簿： 點擊珍藏後，當月色卡會寫入相簿清單，並依照系統設計重置瓶內光珠，為下一個月份的紀錄做準備。
• 時光相簿閱覽： 點擊頁面頂部的「時光相簿」，即可依照時間順序瀏覽歷史封存的月度色卡，並點擊任一張卡片開啟大圖，重溫過去每個月的心情軌跡。

透過下載與封存，微光不再只是當下的互動效果，也成為能夠保存與回顧的生活紀錄。

三、30 天開發技術總結

回顧這 30 天的實作歷程，本專案涵蓋了多個前端開發的重要面向，從資料管理、介面設計到實機測試與正式部署，都經歷了實際的規劃、實作與調整。

1. 框架與邏輯架構

• Vue 3 Composition API： 使用 ref、computed 與 watch 管理響應式狀態、衍生資料與資料變化，讓畫面能依照狀態更新。
• localStorage 本地儲存： 建立本地資料保存機制，讓光珠紀錄、心情標籤與月度色卡等資料能在重新開啟網頁後繼續使用。
• 日期與封存邏輯： 設計日期判斷與封存邊界，並透過 lastArchivedDate 等機制，避免自動補漏邏輯影響已封存的歷史資料。

2. 樣式與視覺體驗

• CSS 微互動動畫： 透過純 CSS 實作光珠掉落、瓶身發光等動畫，增加使用者操作時的視覺回饋。
• 響應式網頁設計： 針對手機直向螢幕調整介面配置與操作方式，提升行動裝置上的使用體驗。
• 動態色彩演算法： 根據每月不同心情顏色的比例計算百分比，並動態組合漸層背景，生成具有個人特色的月度色卡。

3. 實機除錯與自動化部署

• 行動裝置實機測試： 利用 ngrok 建立外部連線，讓 iPhone 能夠實際開啟開發中的網頁，檢查文字對比度、觸控操作與版面呈現。
• Vite 開發伺服器設定： 為了配合 ngrok 測試，曾調整 host 與 allowedHosts 等參數，處理外部連線時的主機名稱檢查問題。這些設定屬於開發階段用途，並非正式部署所必需。
• GitHub Pages 部署： 透過 gh-pages 將 Vite 編譯後的靜態檔案發布至 GitHub Pages，完成從本機開發到公開網站的部署流程。

這些實作不僅讓專案具備完整的操作流程，也讓我更熟悉前端應用程式從開發、測試、除錯到正式發布的整體過程。

四、專案成果展示影片

除了文字說明，也可以透過操作影片，更直觀地了解《微光採集瓶》的功能與互動細節。

1. 日常採集與基礎互動： 展示輸入日常紀錄、選擇心情顏色，以及光珠入瓶的動畫效果。
2. 時光檢索與過去微光回顧： 展示日期篩選、光珠高亮與歷史紀錄檢視。
3. 月底結算、色卡匯出與時光相簿： 展示月底封存動畫、極光色卡生成、圖片下載與相簿瀏覽。
4. 跨月第一天補領機制： 展示進入新月份後，如何透過補領橫幅回顧上個月尚未封存的紀錄。

五、未來可延伸方向

雖然 30 天的挑戰在此告一段落，但《微光採集瓶》仍有許多值得持續改善與擴充的方向。

• 程式碼重構與優化： 整理現有程式架構，簡化重複邏輯，提升程式碼的可讀性與可維護性，為未來的功能擴充打下更好的基礎。
• 光珠視覺質感升級： 進一步調整光珠的透明度、折射、反光與光影層次，使其呈現更自然、真實的玻璃質感，提升整體視覺沉浸感。
• 時光相簿版面優化： 隨著封存月份增加，未來可以採用雙欄網格、月份分類等方式，改善月度色卡的排列與瀏覽體驗，讓回顧過往紀錄更加方便。
• 會員系統與雲端資料同步： 導入使用者註冊、登入與雲端資料庫，讓光珠紀錄、心情標籤與月度色卡能與個人帳號綁定，實現跨裝置同步，降低更換裝置或清除瀏覽器資料時遺失紀錄的風險。
• PWA 與離線使用： 將網站進一步發展為漸進式網頁應用程式（PWA），支援加入手機主畫面與離線使用，讓使用者能更方便地開啟《微光採集瓶》，延續每日採集微光的習慣。

六、完賽感言

從最初在草稿紙上勾勒出「收集日常微光」的想法，到一步步使用 Vue 3 實作資料邏輯、調整 CSS 動畫、解決實機測試中的網路與版面問題，再到今天終於讓《微光採集瓶》正式在 GitHub Pages 上線，這 30 天的挑戰也終於告一段落。

這次的專案讓我從單純的功能實作，逐漸學會如何整合介面設計、資料管理、互動體驗與部署流程。過程中遇到的問題，往往需要反覆測試與調整才能找到合適的解法，而這些實作經驗也是這次挑戰中很重要的收穫。

生活中難免有忙碌，甚至覺得一切都不太順利的時刻。但只要每天願意停下來一分鐘，把一件微小卻真實的美好放進瓶子裡，回頭看時，就會發現那些曾經被忽略的小事，也成了認真生活的證明。

感謝這 30 天一路見證《微光採集瓶》誕生的讀者。從第一道微光到最後一次部署，這段開發旅程也在今天畫下句點。

30 天鐵人賽挑戰，正式完成！