﻿---
title: "設定字典：音樂播放器"
description: "以實際程式碼查閱音樂播放器開關、曲目欄位、預設值、音頻載入方式及多語言文字，說明驗證規則和續播限制。"
url: "https://demo.anglefeint.com/zh-hant/blog/config-music/"
language: "zh-hant"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# 設定字典：音樂播放器

想先放一首自己的歌，讀[音樂設定教學](https://demo.anglefeint.com/zh-hant/blog/starter-guide-3-comments-about-and-theme-toggles/)。設定檔案位置見[安裝與網站資訊](https://demo.anglefeint.com/zh-hant/blog/starter-guide-1-configure-your-site/)，其他模組從[設定字典總入口](https://demo.anglefeint.com/zh-hant/blog/config-reference/)進入。

播放器設定寫在 `src/site.config.ts` 的 `theme.music` 下。主題預設關閉播放器，歌單為空，不附帶預設歌曲。下面說明主題套件的預設值，不以 demo 的個人歌單為準。

## theme.music.enabled：播放器開關

*   **型別 / 預設值：** boolean / false。
*   **狀態與作用：** 生效。為 true 且歌單至少有一首有效歌曲時，標準頁面公共框架才呈現播放器。
*   **限制：** 只寫 true 而不填曲目不會顯示播放器。關閉時曲目不會進入有效執行歌單，且跳過曲目逐項驗證；不會刪除設定或 public 中的音頻檔案，也不限制用戶直接瀏覽已公開檔案。
*   **範例：** `theme: { music: { enabled: false } }`。

開關是全站公共設定，不是為首頁或每種語言分別啟停的開關。使用公共框架的標準頁面共用同一份歌單；不是只能在首頁播放。自訂頁面是否整合公共框架則由頁面自身決定。

## theme.music.tracks：曲目列表

*   **型別 / 預設值：** MusicTrack\[\] / \[\]。每一項的三個欄位見下表。
*   **狀態與作用：** 條件生效，音樂開啟後使用。按陣列順序顯示歌單並切換曲目；沒有公開的條數上限。
*   **限制：** 開啟時必須為陣列；空陣列有效，但有效播放器狀態會變為關閉。覆寫陣列時整體替換，不與預設值或舊歌單拼接。增加歌曲時保留仍要使用的條目。
*   **範例值：** \[{ title: ‘我的一首歌’, artist: ‘作者’, src: ‘`/music/my-song.mp3`’ }\]。

歌曲標題、作者和地址都在這個全站陣列裡，不在 i18n 文字裡；切換頁面語言不會自動換歌單。不要把第三方平臺的歌單物件或分享連結直接當成此陣列。

### 每首歌曲的欄位

完整前綴是 `theme.music.tracks[]`。下表中的“无”表示自訂條目沒有自動補值。

| 欄位 | 型別 / 預設值 | 狀態、作用與限制 | 範例值 |
| --- | --- | --- | --- |
| title | string，必填 / 無 | 條件生效：主顯示區、折疊標題及歌單中的歌曲名稱。必須是非空字串；首尾空白會被移除。空白標題報錯，不從檔案名或音頻標籤生成 | ‘我的一首歌’ |
| artist | string，可省略 / 未設定，正規化為 ‘’ | 條件生效：主顯示區和播放清單中的作者文字。填寫時必須為 string，首尾空白會移除；空值不自動補網站作者，也不讀取音訊中繼資料 | ‘作者’ |
| src | string，必填 / 無 | 條件生效：音頻來源地址；必須以單個 / 或小寫 https:// 開頭，不能含空白或反斜線。HTTPS 地址還需能通過 URL 解析；不檢查檔案是否存在或內容是否為音頻 | ‘/music/my-song.mp3’ |

title 和 artist 按文字顯示，不解析 Markdown 或 HTML。沒有公開的封面、歌詞、時長、專輯、獨立 ID 或按曲目設定音量的欄位。

src 的限制需要分清：

*   本機檔案建議放 `public/music/`，設定使用 /music/檔案名，不寫 public 前綴，不寫 Windows 磁磁碟路徑或 src/assets 原始碼路徑。實作接受符合規則的其他根路徑，並不強制位於 /music/，也不按擴展名確認音頻格式。
*   不接受 [http://、//example.com/file.mp3、data:、blob](http://xn--q6j//example.com/file.mp3%E3%80%81data:%E3%80%81blob): 或一般相對路徑。HTTPS 前綴驗證區分大小寫；範例統一使用小寫 [https://。](https://./)
*   地址不能直接帶空格；需要時對路徑做 URL 編碼，但編碼正確不代表伺服器上一定有對應檔案。不要在地址首尾添加空格。
*   根路徑在呈現時自動加上 Astro 的 BASE\_URL；使用子路徑部署時不要自行重複添加同一前綴。HTTPS 地址保持原值。
*   格式正確只表示設定通過。檔案仍需由瀏覽器支援並可瀏覽；平臺分享頁面不等於音頻直鏈。外鏈以 fetch 下載，伺服器必須允許目前網站跨域讀取；僅能在新標籤頁播放，不代表允許 CORS。

播放器用 src 還原已保存的曲目，建議每首使用不同地址。重複 src 沒有被設定驗證禁止，但還原時會匹配第一個相同地址；標題不是還原識別碼。

## 可合併的歌單範例

先自行準備 `public/music/my-song.mp3`。下面的路徑是範例，主題不會替你生成音頻檔案。將片段合併到 `src/site.config.ts` 現有的 `defineThemeConfig({...})`，保留 import、export 和其他個人設定，不要重複建立 theme。

```ts
theme: {
  music: {
    enabled: true,
    tracks: [
      {
        title: '我的一首歌',
        artist: '作者',
        src: '/music/my-song.mp3',
      },
    ],
  },
},
```

只關閉播放器時設定 `enabled: false`；不必清空歌單。修改設定後開發服務需要重新讀取設定，線上網站則需重新建置部署；僅上傳音頻但未登記 tracks 不會自動加入歌單。

## messages.music：十九項介面與無障礙文字

完整前綴是 `i18n.locales.<locale>.messages.music.`。每項均為可省略的 **string**，預設來自內建目前語言文字和語言回退鏈。下表只列中文 / 英文預設值，範例列是欄位值；生效條件是播放器已呈現且對應控制項或狀態出現。空字串會覆寫文字，不是隱藏功能的開關，也可能使控制項失去清楚的無障礙名稱。

| 欄位 | 簡體中文 / 英文預設值 | 作用與限制 | 範例值 |
| --- | --- | --- | --- |
| `label` | 音乐播放器 / Music player | 播放器 aside 區域的無障礙名稱，不是頂部 AUDIO CHANNEL 文字 | `"音樂播放器"` |
| `play` | 播放 / Play | 播放按鈕的無障礙名稱；可見按鈕仍為 PLAY | `"播放"` |
| `pause` | 暂停 / Pause | 播放中或載入中按鈕的無障礙名稱；可見按鈕為 PAUSE | `"暫停"` |
| `prev` | 上一首 / Previous | 上一首按鈕的無障礙名稱；可見文字為 PREV | `"上一首"` |
| `next` | 下一首 / Next | 下一首按鈕的無障礙名稱；可見文字為 NEXT | `"下一首"` |
| `open` | 展开播放器 / Open player | 折疊狀態下展開按鈕的無障礙名稱；可見文字為 OPEN | `"展開播放器"` |
| `close` | 收起播放器 / Collapse player | 展開狀態下收起按鈕的無障礙名稱；可見文字為 MIN。收起不暫停播放 | `"收起播放器"` |
| `progress` | 播放进度 / Progress | 進度滑塊的無障礙名稱，不改變進度或可跳轉範圍 | `"播放進度"` |
| `volume` | 音量 / Volume | 音量滑塊的無障礙名稱，不設定預設音量；可見標籤仍為 LVL | `"音量"` |
| `queue` | 歌单 / Playlist | 歌單展開按鈕的無障礙名稱；可見 QUEUE、SHOW / HIDE 等文字固定 | `"展開或收起歌單"` |
| `mute` | 静音 / Mute | 非靜音時靜音按鈕的無障礙名稱；可見文字為 MUTE | `"靜音"` |
| `unmute` | 取消静音 / Unmute | 音量為零時還原音量按鈕的無障礙名稱；可見文字為 UNMUTE | `"恢復音量"` |
| `idle` | 就绪 / Ready | 初始或切換歌曲後的 SIGNAL 狀態文字 | `"等待播放"` |
| `loading` | 加载中 / Loading | 歌曲下載或等待播放時的 SIGNAL 狀態文字 | `"正在載入歌曲"` |
| `playing` | 播放中 / Playing | 正在播放時的 SIGNAL 狀態文字 | `"正在播放"` |
| `paused` | 已暂停 / Paused | 暫停時的 SIGNAL 狀態文字 | `"已暫停"` |
| `blocked` | 浏览器阻止了自动播放，请点击 PLAY 继续播放。 / Click Play to continue. Your browser blocked automatic playback. | 瀏覽器拒絕播放權限時的提示；不能通過改文字解除限制 | `"請點擊播放以繼續。"` |
| `error` | 播放失败，请重试或切换歌曲。 / Unable to play. Try again or select another track. | 音頻請求、播放失敗的狀態，以及播放器掛載模組失敗時的提示 | `"歌曲未能載入，請重試。"` |
| `noScript` | 请启用 JavaScript 使用播放器。 / Enable JavaScript to use the player. | 瀏覽器停用 JavaScript 時的 noscript 提示，不會提供原生音頻替代控制項 | `"啟用 JavaScript 后可以使用播放器。"` |

這些文字不是整套終端機 UI 的可見文字替換表。PLAY / PAUSE、PREV / NEXT、OPEN / MIN、MUTE / UNMUTE、QUEUE、SHOW / HIDE、TRACKS、LVL、AUDIO CHANNEL、STATE、SIGNAL 和 STANDBY 等狀態代號由實作固定；對應可設定欄位用於無障礙名稱或 SIGNAL 行的可見狀態，不能因為按鈕仍顯示英文就把欄位判斷為未生效。

例如只覆寫繁體中文載入和錯誤提示：

```ts
i18n: {
  locales: {
    'zh-hant': {
      messages: {
        music: {
          loading: '正在載入歌曲',
          error: '歌曲未能載入，請重試。',
        },
      },
    },
  },
},
```

語言啟用和回退見[多語言教學](https://demo.anglefeint.com/zh-hant/blog/starter-guide-languages/)。音樂文字遵循語言，曲目陣列仍是全站共享。

## 音頻何時下載，為什麼有時需要等待？

首次使用且沒有已保存續播狀態時，初始化介面不建立音頻下載；點選播放、上一首、下一首或歌單曲目才請求所選音頻。單純展開面板或歌單不會下載整份歌單。還原同一標籤頁的續播狀態時，也可能自動發起所選歌曲請求。

目前播放器先完整下載所選音頻，轉成 Blob，再交給 Audio 播放；不是下載一點就開始的串流播放。這樣即使伺服器忽略 Range 請求，已下載內容仍可跳轉進度。大檔案會增加首次等待與內存佔用；音頻來源不會由主題自動轉碼、壓縮或生成不同碼率。

暫停後再次播放會重複使用目前音頻和已下載的 Blob。切換到另一首會中止未完成的下載並釋放舊資源，切回可能重新請求；伺服器和瀏覽器 HTTP 快取是否命中是另一層行為，不代表播放器永久快取了全部歌曲。失敗不會自動跳過壞歌；可再次點選播放重試。播放權限被瀏覽器拒絕時顯示 blocked 提示，仍需用戶操作。

外鏈必須允許 CORS，且下載應返回成功狀態；主題沒有設定代理、授權請求頭或自訂憑據的入口。同網站 public 音頻無需額外跨域設定。修改提示文字不會修復音頻路徑、權限或格式問題。

## 播放、續播、外觀：固定行為與設定邊界

| 專案 | 目前實際行為 | 是否是 site.config 欄位 |
| --- | --- | --- |
| 預設選曲 | 沒有可匹配的已保存歌曲時選第一首；匹配依據是解析後的 src | 否，沒有 defaultTrack |
| 預設音量 | 首次為 0.5，之後可以還原同標籤頁保存的音量 | 否，沒有 defaultVolume |
| 靜音 | 將音量設為零；還原時使用記住的非零音量，不停止下載或暫停播放 | 否，沒有獨立 mute 設定 |
| 自動下一首 | 播放結束後切到下一項，最後一項後回到第一項；不是隨機播放 | 否，沒有 shuffle / repeat / loop 設定 |
| 續播 | sessionStorage 保存歌曲地址、進度、音量、收起狀態與續播意圖；可用時在同標籤頁導覽或還原頁面後嘗試續播，受瀏覽器權限影響 | 否，沒有 autoplay / resume 設定 |
| 面板初始狀態 | 標準播放器組件預設收起；初始組件參數優先于保存的顯示偏好，BFCache 還原另有狀態還原邏輯 | 否，沒有 theme.music.collapsed |
| 收起、展開與歌單 | 只改變介面，不暫停播放；Escape 可收起展開的面板 | 否，沒有通過 site.config 修改快捷鍵的欄位 |
| 頁面風格 | 公共框架按目前頁面選擇 Matrix / Cyber / Hacker / AI 或基礎外觀；不是按歌曲型別選擇 | 否，沒有 theme.music.scene |
| 動畫 | Matrix 使用自己的視覺效果，結合播放狀態、頁面可見性與收起狀態執行；同時遵循系統減少動態效果偏好；效果失敗不應阻止音頻 | 否，沒有音樂專屬效果開關 |

sessionStorage 是會話狀態，不是永久雲端記錄，也不是跨標籤頁同步協議。保存受限時播放器仍可工作，但不能保證還原狀態；不保證跨頁面無縫、無中斷播放。瀏覽器不支援 JavaScript 時，顯示 noScript 提示，播放器互動不可用。

組件或自訂布局的 `initiallyCollapsed`、`musicInitiallyCollapsed`、`scene` 等參數不是公開的 site.config 欄位，不要直接添加到 `theme.music` 期待生效。標準頁面目前預設收起；用戶可在介面展開。曲目和標題文字也不會觸發主題氣氛自動切換。

目前音樂模組的兩個設定欄位、三個曲目欄位和十九項文字都有消費位置，沒有額外的相容或停用欄位需要填寫。文字的無障礙用途、固定英文顯示和會話狀態已在上文區分。返回[設定字典總入口](https://demo.anglefeint.com/zh-hant/blog/config-reference/)查其他模組。
