一、本地构建
前置环境配置
核心依赖
- 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. 获取源代码
首先把代码拉取到本地：
git clone https://git.unlock-music.dev/um/web.git或者在项目仓库下载。
2. 确认 Node 版本
在终端输入命令检查当前版本：
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.json4. 安装项目依赖
执行安装命令：
npm install注：请使用npm install而非npm ci，因为在首次构建或切换 Node 版本后，通常需要重新生成 lock 文件。
5. 开始构建
5.1 开发模式（用于调试）
如果你想边修改代码边预览效果，运行：
npm run serve启动后，在浏览器中访问 http://localhost:8080 即可实时查看。 
5.2 生产环境构建（用于部署）
如果你需要将应用部署到服务器，运行：
npm run build构建完成后，所有生成的文件将位于 dist 目录中，将其上传至服务器即可运行。 
6. 制作浏览器插件（可选）
如果你想将其打包为浏览器扩展程序，运行：
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 快速构建镜像并运行：
docker build -t unlock-music-web .
docker run -d -p 80:80 unlock-music-web方案三：安装浏览器扩展
按照以下步骤，将构建好的扩展加载到浏览器中，即可在任意网页上便捷使用。
Chrome / Edge 浏览器安装步骤：
1.打开浏览器扩展管理页面
2.开启开发者模式
在页面右上角找到并打开开发者模式开关
3.加载扩展
点击“加载已解压的扩展程序”按钮
在弹出的文件选择窗口中，定位并选择项目的 dist 目录
点击“选择文件夹”完成加载
4.确认安装成功
扩展列表中会出现“音乐解锁”扩展卡片
确保扩展处于启用状态 
Firefox 浏览器安装步骤：
1.打开调试页面
地址栏输入 about:debugging#/runtime/this-firefox
2.临时加载附加组件
点击“临时载入附加组件”按钮
选择 dist 目录下的 manifest.json 文件
点击“打开”完成加载
使用扩展：
打开后和网页版的一样
注意：通过开发者模式加载的扩展在浏览器重启后可能需要重新加载。如需长期使用，建议通过官方扩展商店安装正式版本。
方案四：本地离线运行
直接下载并解压已构建好的产物包，在浏览器中打开 index.html 文件即可运行（注：此方式通常仅适用于 legacy 版本）。
三、安全与使用须知
隐私保护
1.纯本地运算：所有解密操作均在您的浏览器内部完成，程序不会将任何音频文件上传至服务器。
2.网络请求：仅在需要在线匹配专辑封面或同步元数据时，才会发起极少量的网络请求。
3.环境建议：为保障数据传输安全，建议在 HTTPS 协议下访问。同时，HTTPS 环境也能启用 Web Worker 以获得更好的并行处理性能。
效能建议
1.处理大量文件：如果您需要处理数以万计的音乐文件，建议使用 CLI 命令行版本，效率更高。
2.浏览器兼容性：推荐使用最新版本的 Chrome、Edge 或 Firefox 浏览器，以获得最佳的性能和兼容性。
UnlockMusic最新文章：
[PostCard cid=3724]
觉得内容不错？我要
