﻿---
title: "配置字典：音乐播放器"
description: "以实际代码查阅音乐播放器开关、曲目字段、默认值、音频加载方式及多语言文案，说明验证规则和续播限制。"
url: "https://demo.anglefeint.com/zh/blog/config-music/"
language: "zh"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-13T00:00:00.000Z"
---

# 配置字典：音乐播放器

想先放一首自己的歌，读[音乐设置教程](https://demo.anglefeint.com/zh/blog/starter-guide-3-comments-about-and-theme-toggles/)。配置文件位置见[安装与站点信息](https://demo.anglefeint.com/zh/blog/starter-guide-1-configure-your-site/)，其他模块从[配置字典总入口](https://demo.anglefeint.com/zh/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.<语言>.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: {
      messages: {
        music: {
          loading: '正在加载歌曲',
          error: '歌曲未能加载，请重试。',
        },
      },
    },
  },
},
```

语言启用和回退见[多语言教程](https://demo.anglefeint.com/zh/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/blog/config-reference/)查其他模块。
