文章来源说明：

作者： [xuan]
发布平台： [Xuan’s blog]
原链接： https://blog.ybyq.wang/archives/1570.html
发布时间： [2026-01-29]
转载用途： 仅供学习和技术交流

版权归原作者所有，本文仅做整理和分享之用。

UnlockMusic 本地构建、服务器部署与浏览器扩展制作教程

本地构建

前置环境配置

核心依赖

Node.js: 运行环境请务必锁定为 v16.x 版本。该项目暂不支持 v17 及更高版本，强行使用会导致编译失败。
npm: 推荐直接使用 Node.js v16 自带的包管理工具（npm v8.x），以规避潜在的版本冲突。

警告: 本项目基于 Vue CLI 4 与 Webpack 4 开发，与 Node.js v17+ 存在底层不兼容。若版本不匹配，编译流程将无法正常完成。

WASM 组件（可选）

操作系统：Linux
环境支持：Python 3

在线预览

地址：unlock-music

详细操作步骤

1. 获取源代码

首先把代码拉取到本地：

1	git clone https://git.unlock-music.dev/um/web.git

或者在项目仓库下载。

2. 确认 Node 版本

在终端输入命令检查当前版本：

1	node --version

如果环境不符合 v16.x 要求，请按以下方式切换：

通过 nvm 管理（推荐）：

# 安装 Node.js v16
nvm install 16
# 切换到 v16 环境
nvm use 16

（以上命令在 Windows/Linux/macOS 上均适用，nvm 的具体安装请参照对应平台的指南。）

手动安装：若未安装 nvm，请前往 Node.js 历史版本库获取安装包。

3. 清理旧依赖（建议执行）

如果你之前用其他 Node 版本运行过该项目，为稳妥起见，建议先清理旧的依赖文件：

# Windows PowerShell 环境
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json

# Linux/macOS 环境
rm -rf node_modules package-lock.json

4. 安装项目依赖

执行安装命令：

1	npm install

注：请使用 npm install 而非 npm ci，因为在首次构建或切换 Node 版本后，通常需要重新生成 lock 文件。

5. 开始构建

5.1 开发模式（用于调试）

如果你想边修改代码边预览效果，运行：

1	npm run serve

启动后，在浏览器中访问 http://localhost:8080 即可实时查看。

5.2 生产环境构建（用于部署）

如果你需要将应用部署到服务器，运行：

1	npm run build

构建完成后，所有生成的文件将位于 dist 目录中，将其上传至服务器即可运行。

6. 制作浏览器插件（可选）

如果你想将其打包为浏览器扩展程序，运行：

1	npm run make-extension

构建成功后会在 dist 目录生成三个扩展文件：popup.html、popup.js 和 manifest.json。

常见报错及解决方法

报错 1: error:0308010C:digital envelope routines::unsupported

原因：典型的 OpenSSL 兼容性问题，通常由 Node.js 版本过高引起。
解决：将 Node.js 降级至 v16.x 即可。

报错 2: parser.state.module.addPresentationalDependency is not a function

原因：全局安装了 Webpack 5，与项目内的 Webpack 4 产生冲突。
解决：

# 1. 移除全局冲突的 webpack
npm uninstall -g webpack
# 2. 彻底清理并重装项目依赖
rm -rf node_modules package-lock.json
npm install

报错 3: npm 环境警告

如果看到类似 npm warn cli npm v11.x.x does not support Node.js v16.x.x 的提示，通常可以忽略，这仅是版本跨度提示，一般不影响最终构建结果。

目录结构说明

构建完成后，dist 目录结构大致如下：

dist/
├── index.html          # 应用主入口页面
├── loader.js           # 资源预加载脚本
├── css/                # 样式文件目录
├── js/                 # 核心逻辑及 Web Worker 脚本
├── img/                # 图片等静态资源
└── service-worker.js   # 离线应用支持脚本

部署方案选择

方案一：Nginx 静态托管

将 dist 目录下的所有文件上传至你的 Nginx、Apache 服务器或任意静态托管服务/CDN。

基础 Nginx 配置参考：

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/your/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

方案二：Docker 容器化部署

使用项目提供的 Dockerfile 快速构建镜像并运行：

1 2	docker build -t unlock-music-web . docker run -d -p 80:80 unlock-music-web

方案三：安装浏览器扩展

按照以下步骤，将构建好的扩展加载到浏览器中，即可在任意网页上便捷使用。

Chrome / Edge 浏览器安装步骤：

打开浏览器扩展管理页面
开启开发者模式
- 在页面右上角找到并打开开发者模式开关
加载扩展
- 点击”加载已解压的扩展程序”按钮
- 在弹出的文件选择窗口中，定位并选择项目的 dist 目录
- 点击”选择文件夹”完成加载
确认安装成功
- 扩展列表中会出现”音乐解锁”扩展卡片
- 确保扩展处于启用状态

Firefox 浏览器安装步骤：

打开调试页面
- 地址栏输入 about:debugging#/runtime/this-firefox
临时加载附加组件
- 点击”临时载入附加组件”按钮
- 选择 dist 目录下的 manifest.json 文件
- 点击”打开”完成加载

使用扩展：

打开后和网页版的使用方式一样。

注意：通过开发者模式加载的扩展在浏览器重启后可能需要重新加载。如需长期使用，建议通过官方扩展商店安装正式版本。

方案四：本地离线运行

直接下载并解压已构建好的产物包，在浏览器中打开 index.html 文件即可运行（注：此方式通常仅适用于 legacy 版本）。

安全与使用须知

隐私保护

纯本地运算：所有解密操作均在您的浏览器内部完成，程序不会将任何音频文件上传至服务器。
网络请求：仅在需要在线匹配专辑封面或同步元数据时，才会发起极少量的网络请求。
环境建议：为保障数据传输安全，建议在 HTTPS 协议下访问。同时，HTTPS 环境也能启用 Web Worker 以获得更好的并行处理性能。

效能建议

处理大量文件：如果您需要处理数以万计的音乐文件，建议使用 CLI 命令行版本，效率更高。
浏览器兼容性：推荐使用最新版本的 Chrome、Edge 或 Firefox 浏览器，以获得最佳的性能和兼容性。