unlock-music项目安装依赖及启动相关报错问题及解决

今晚翻倒一起的音乐解锁相关项目源码，于是进行启动测试，发现原本项目作者仓库已经删除了，随后用ai重构

依赖无法下载问题总结与修复记录

项目地址：https://gitee.com/suifenglzy/unlock-music

问题描述

unlock-music 项目（v1.10.0）在 npm install 时因以下两个依赖包已从 npm 官方仓库永久删除而安装失败：

依赖包	版本	用途
@jixun/qmc2-crypto	0.0.6-R1	QMC2 格式（QQ 音乐新格式 .mgg/.mflac）的 WASM 加解密
@unlock-music/joox-crypto	0.0.1-R5	JOOX Music 海外版格式解密

两个包无论在 registry.npmjs.org 还是 registry.npmmirror.com 均返回 404，无法安装，导致项目完全无法运行

解决思路

参考同级目录下已能正常运行的 音乐解锁dist/dist（v1.8.0）已构建代码，发现其完全不依赖这两个包，而是使用纯 JS 实现的 QmcDecoder 处理 QMC 格式解密。因此核心策略是：

1. 移除已删除的 npm 依赖

2. 用纯 JS 降级方案替代 qmc_wasm.ts 的 WASM 解密

3. 禁用 JOOX 解密（无可用替代方案）

4. 修复 TypeScript 编译错误

修改文件清单

文件	修改内容
package.json	移除 @jixun/qmc2-crypto 和 @unlock-music/joox-crypto
src/decrypt/qmc_wasm.ts	重写为始终返回失败，自动触发 qmc.ts 中纯 JS QmcDecoder fallback
src/decrypt/joox.ts	重写为抛出友好错误提示，移除所有已删除包的 import
src/decrypt/index.ts	修正 JooxDecrypt() 调用，移除传入的参数
src/shims-element-ui.d.ts	新增，解决 element-ui 缺少类型声明的 TS 编译错误
package-lock.json	删除旧 lockfile，重新生成以排除已删除包的记录
README.md	补充安装注意事项和已知问题说明

具体修改详情

1. package.json --- 移除依赖

  "dependencies": {
    "@babel/preset-typescript": "^7.16.5",
-   "@jixun/qmc2-crypto": "^0.0.6-R1",
-   "@unlock-music/joox-crypto": "^0.0.1-R5",
    "base64-js": "^1.5.1",
    ...
  }

2. src/decrypt/qmc_wasm.ts --- 改为 fallback

原文件导入并调用 @jixun/qmc2-crypto 的 WASM 模块进行 QMC2 检测和解密（约111行）

修改后：

export async function DecryptQMCWasm(): Promise<QMC2DecryptionResult> {
  return {
    success: false,
    data: new Uint8Array(),
    songId: 0,
    error: 'QMC2 WASM 解密不可用（@jixun/qmc2-crypto 已删除），将自动使用 JS 解码器',
  };
}

由于 qmc.ts 中已有完整的 fallback 逻辑（v2Decrypted.success 为 false 时自动使用 QmcDecoder），此改动无需修改 qmc.ts 主体逻辑

3. src/decrypt/joox.ts --- 禁用 JOOX

JOOX 解密没有可用的纯 JS 替代方案，改为抛出明确错误：

export async function Decrypt(): Promise<DecryptResult> {
  throw new Error('@unlock-music/joox-crypto 包已从 npm 删除，JOOX 解密功能暂时不可用。');
}

4. src/decrypt/index.ts --- 修正调用

   case 'ofl_en':
-     rt_data = await JooxDecrypt(file.raw, raw.name, raw.ext);
+     rt_data = await JooxDecrypt();
      break;

5. src/shims-element-ui.d.ts --- 新增类型声明

element-ui 的 @types/element-ui 包不存在，创建 shim 文件解决 TS 编译错误 TS7016：

declare module 'element-ui';

6. 删除 package-lock.json

旧 lockfile 中仍记录了已删除的两个包，删除后重新生成干净的 lockfile

功能影响

功能	修复前	修复后
QMC 旧格式（.qmc0/.qmc2/.qmc3）	✅	✅
QMC 新格式（.mgg/.mflac）WASM 加速	✅	⚠️ 降级为 JS 解码（稍慢但仍可用）
网易云音乐 .ncm	✅	✅
虾米音乐 .xm	✅	✅
酷我音乐 .kwm	✅	✅
酷狗音乐 .kgm/.vpr	✅	✅
JOOX Music .ofl_en	✅	❌ 已不可用（无替代方案）

安装与运行

# 使用 npmmirror 镜像源（推荐，国内网络更快）
npm config set registry https://registry.npmmirror.com
npm install --ignore-scripts
​
# 开发运行
npm run serve
​
# 构建生产版本
npm run build

时间线

• 问题发现 ：npm install 时报 E404，两个包均不可用

• 对比分析 ：参考 音乐解锁dist 的 dist 构建产物，确认纯 JS 方案可行

• 代码修改：移除依赖 + 重写 3 个源文件 + 新增 1 个类型声明文件

• 验证 ：npm install ✅ + npm run build ✅