1396 字

7 分鐘

🎵 灰產進行曲丨音樂開發紀錄

2025-07-29

🧭 指南向

Astro

/

JavaScript

正在播放灰產進行曲

背景音樂功能開發記錄#

📋 功能概述#

為 Astro 靜態網站實現了完整的背景音樂功能，包括：

✅ 自動播放背景音樂
✅ 圖標式播放/暫停控制
✅ 音量控制
✅ 循環播放設置
✅ 音樂狀態顯示
✅ 檔名顯示

🎯 開發過程記錄#

1. 初始問題與解決#

問題：MP3 文件無法播放

1
// 低級問題
2
原始代碼：src="./灰產進行曲.mp3"
3
問題：相對路徑無法正確解析

解決方案：

1
1. 將 MP3 文件移動到 public/ 目錄
2
2. 修改路徑為絕對路徑：src="/灰產進行曲.mp3"
3
3. 在 frontmatter 中設置：audio: "/灰產進行曲.mp3"

2. 架構設計演進#

第一階段：內聯音頻標籤#

1
<audio src="/灰產進行曲.mp3" controls autoplay loop></audio>

第二階段：獨立組件#

1
<audio id="background-audio" preload="auto" autoplay loop>
2
    <source src={audio} type="audio/mpeg">
3
</audio>

第三階段：整合到 PostMeta 組件#

1
{audio && (
2
    <div class="flex items-center">
3
        <div class="meta-icon">
4
            <button id="play-pause-btn">
5
                <Icon id="play-icon" name="material-symbols:play-arrow-rounded" />
6
                <Icon id="pause-icon" name="material-symbols:pause-rounded" />
7
            </button>
8
        </div>
9
        <div class="flex flex-row flex-nowrap items-center">
10
            <span id="music-status">
11
                <span id="status-text">正在播放</span>
12
                <span id="music-filename">{audio.split('/').pop()?.replace('.mp3', '')}</span>
13
            </span>
14
        </div>
15
    </div>
16
)}

3. 核心技術實現#

3.1 內容集合配置 (src/content/config.ts)#

1
const postsCollection = defineCollection({
2
    schema: z.object({
3
        // ... 其他字段
4
        audio: z.string().optional().default(""), // 背景音樂文件路徑
5
        audioLoop: z.boolean().optional().default(true), // 是否循環播放
6
        audioVolume: z.number().optional().default(20), // 音量大小 (0-100，0為靜音，100為最大音量)
7
    }),
8
});

3.2 組件 Props 接口 (src/components/PostMeta.astro)#

1
interface Props {
2
    // ... 其他屬性
3
    audio?: string;
4
    audioLoop?: boolean;
5
    audioVolume?: number;
6
}

3.3 JavaScript 控制邏輯#

1
function initAudioControls() {
2
    const audio = document.getElementById('background-audio');
3
    const playPauseBtn = document.getElementById('play-pause-btn');
4
    const playIcon = document.getElementById('play-icon');
5
    const pauseIcon = document.getElementById('pause-icon');
6
    const statusText = document.getElementById('status-text');
7

8
    // 設置音量 (0-100 轉換為 0.0-1.0)
9
    const volumeData = document.querySelector('[data-audio-volume]');
10
    const volumePercent = volumeData ? parseFloat(volumeData.getAttribute('data-audio-volume')) : 20;
11
    audio.volume = volumePercent / 100;
12

13
    // 自動播放
14
    audio.play().then(() => {
15
        console.log('音樂自動播放成功');
16
    }).catch((e) => {
17
        console.log('自動播放被阻止:', e);
18
    });
19

20
    // 播放/暫停控制
21
    playPauseBtn.addEventListener('click', () => {
22
        if (audio.paused) {
23
            audio.play().catch((e) => console.log('播放失敗:', e));
24
        } else {
25
            audio.pause();
26
        }
27
    });
28

29
    // 狀態更新
30
    audio.addEventListener('play', () => {
31
        playIcon.classList.add('hidden');
32
        pauseIcon.classList.remove('hidden');
33
        statusText.textContent = '正在播放';
34
    });
35

36
    audio.addEventListener('pause', () => {
37
        playIcon.classList.remove('hidden');
38
        pauseIcon.classList.add('hidden');
39
        statusText.textContent = '已暫停';
40
    });
41
}

4. 遇到的問題與解決#

4.1 瀏覽器自動播放限制#

問題：現代瀏覽器阻止未經用戶交互的自動播放 解決方案：

1
// 使用 is:inline 腳本確保立即執行
2
<script is:inline>
3
    (function() {
4
        // 立即執行初始化
5
        initAudioControls();
6

7
        // 多重保險：DOMContentLoaded 和 window.load
8
        if (document.readyState === 'loading') {
9
            document.addEventListener('DOMContentLoaded', initAudioControls);
10
        }
11
        window.addEventListener('load', initAudioControls);
12
    })();
13
</script>

4.2 按鈕交互問題#

問題：首次進入頁面按鈕無法交互，需要刷新 解決方案：

1
// 重試機制
2
if (!audio || !playPauseBtn || !playIcon || !pauseIcon || !statusText) {
3
    setTimeout(initAudioControls, 50);
4
    return;
5
}

4.3 音量控制實現#

需求：讓用戶可以在 frontmatter 中設置音量實現：

1
# 在文章 frontmatter 中
2
audioVolume: 20  # 音量大小 (0-100，0為靜音，100為最大音量)

音量範圍調整：

原始設計：0.0-1.0（HTML5 Audio API 標準）
用戶需求：0-100（更直觀的百分比）
實現方案：在 JavaScript 中將百分比轉換為 0.0-1.0

1
// 音量轉換邏輯
2
const volumePercent = volumeData ? parseFloat(volumeData.getAttribute('data-audio-volume')) : 20;
3
audio.volume = volumePercent / 100; // 將百分比轉換為 0.0-1.0

4.4 音量調整優化#

問題：默認音量過大，可能嚇到讀者 解決方案：

調整默認音量：從 30% 降低到 20%
使用百分比範圍：0-100 比 0.0-1.0 更直觀
用戶體驗考慮：避免突然的大音量播放

修改文件：

src/content/config.ts：默認音量從 0.3 改為 20
src/components/PostMeta.astro：添加百分比轉換邏輯

5. 最終功能特性#

5.1 Frontmatter 配置#

1
---
2
title: 文章標題
3
audio: "/音樂文件.mp3"     # 音樂文件路徑（相對於 public 目錄）
4
audioLoop: true           # 是否循環播放
5
audioVolume: 20          # 音量大小 (0-100，0為靜音，100為最大音量)
6
---