fix(qq): pin @sansenjian/qq-music-api to ~2.4.0 + guard startup failures

A loose `^2.2.10` range let npm pull a newer build of the QQ Music API. The
library went ESM in 2.3.x: an ESM-only 2.3.0/2.3.1 throws ERR_REQUIRE_ESM on
load, so the embedded server never binds port 3200 and every QQ request
(including /getQQLoginQr) fails downstream with ECONNREFUSED — the QR code never
appears and cookies look broken.

- Pin to `~2.4.0` (verified: loads via the bot's native ESM import, exposes the
  Koa app, and every endpoint qq.ts calls returns the exact shapes it parses —
  QR, recommend, lyric, play, playlist detail). Blocks the broken 2.3.0/2.3.1
  and any future 2.5 migration. NOTE: 2.4.x requires Node >=20.17 (or >=22.9).
- Add describeQqApiStartupError(): on startup failure, log an actionable error
  (ERR_REQUIRE_ESM → version-pin hint; engine mismatch → Node-upgrade hint)
  instead of a generic warning, so this is obvious from the logs next time.
- README: troubleshooting entry for "QQ 二维码不弹 / 登录失败 / cookie 无法使用"
  and the version/Node note in the dependency table.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
saopig1andClaude Opus 4.8 committed 2026-06-30 23:05:47 +08:00
1 parent de4343cfbb
commit 08260182a9
5 files changed
+101 -47

No files matched your search

+25 -41
View File
@@ -12,7 +12,7 @@
"@discordjs/opus": "^0.10.0",
"@honeybbq/teamspeak-client": "^0.2.1",
"@koa/router": "^15.4.0",
"@sansenjian/qq-music-api": "^2.2.10",
"@sansenjian/qq-music-api": "~2.4.0",
"axios": "^1.14.0",
"bcryptjs": "^2.4.3",
"better-sqlite3": "^12.8.0",
@@ -595,15 +595,15 @@
"license": "MIT"
},
"node_modules/@koa/router": {
"version": "15.4.0",
"resolved": "https://registry.npmjs.org/@koa/router/-/router-15.4.0.tgz",
"integrity": "sha512-vKYlXtoCfcAN8z4dHiveYX55rTYOgHEYJNumK1WM9ZAwaArhreGVkyC1LTMGfUQUJyIO/SbwRFBOHeOCY8/MaQ==",
"version": "15.6.0",
"resolved": "https://registry.npmjs.org/@koa/router/-/router-15.6.0.tgz",
"integrity": "sha512-iEOXlvGIBqSNkGXrg0XtMARAOm5zA24oedXxiTGEkrD4JgwVjfRDddCQvW1s4WEcwDYvyecRbf8BikXsuEEj8w==",
"license": "MIT",
"dependencies": {
"debug": "^4.4.3",
"http-errors": "^2.0.1",
"koa-compose": "^4.1.0",
"path-to-regexp": "^8.3.0"
"path-to-regexp": "^8.4.2"
},
"engines": {
"node": ">= 20"
@@ -967,25 +967,24 @@
"license": "MIT"
},
"node_modules/@sansenjian/qq-music-api": {
"version": "2.2.10",
"resolved": "https://registry.npmjs.org/@sansenjian/qq-music-api/-/qq-music-api-2.2.10.tgz",
"integrity": "sha512-EjhZ3s+ZErSrO6jt5BkThIq6hmMFfvr6RNg945m8SrBOHfuih0cC2kbpoz7WgwnOXoq/psN8iVG/jXrYRUFyQA==",
"version": "2.4.0",
"resolved": "https://registry.npmjs.org/@sansenjian/qq-music-api/-/qq-music-api-2.4.0.tgz",
"integrity": "sha512-yPV5h/Qd+oVOKVmDrG0C/r+Xs1QUXcE1Eo16aJYwY9Fugg3CoEaAYFYtitwSIQD6PpnuXqVqWIIot+gtLeAXOQ==",
"license": "MIT",
"workspaces": [
"packages/mcp"
],
"dependencies": {
"@koa/router": "^15.3.1",
"axios": "^1.13.6",
"date-fns": "^4.1.0",
"is-generator-function": "1.0.10",
"koa": "^2.16.1",
"koa-bodyparser": "^4.4.1",
"koa-static": "^5.0.0",
"reflect-metadata": "^0.2.2"
"@koa/router": "^15.5.0",
"axios": "^1.16.1",
"koa": "^2.16.4"
},
"bin": {
"qq-music-api": "dist/app.js"
"qq-music-api": "dist/cli.js"
},
"engines": {
"node": "22.x"
"node": "^20.17.0 || >=22.9.0",
"npm": "^11.0.0"
}
},
"node_modules/@sansenjian/qq-music-api/node_modules/accepts": {
@@ -1639,13 +1638,14 @@
}
},
"node_modules/axios": {
"version": "1.15.0",
"resolved": "https://registry.npmjs.org/axios/-/axios-1.15.0.tgz",
"integrity": "sha512-wWyJDlAatxk30ZJer+GeCWS209sA42X+N5jU2jy6oHTp7ufw8uzUTVFBX9+wTfAlhiJXGS0Bq7X6efruWjuK9Q==",
"version": "1.18.1",
"resolved": "https://registry.npmjs.org/axios/-/axios-1.18.1.tgz",
"integrity": "sha512-3nTvFlvpn9Zu/RkHUqtc7/+al4UpRW5az71ap5zccp6e8RAYEzhMTecX8Dz1wWDYrPpUoB1HAQEGEAEvUr7S9g==",
"license": "MIT",
"dependencies": {
"follow-redirects": "^1.15.11",
"follow-redirects": "^1.16.0",
"form-data": "^4.0.5",
"https-proxy-agent": "^5.0.1",
"proxy-from-env": "^2.1.0"
}
},
@@ -2275,16 +2275,6 @@
"node": ">= 14"
}
},
"node_modules/date-fns": {
"version": "4.1.0",
"resolved": "https://registry.npmjs.org/date-fns/-/date-fns-4.1.0.tgz",
"integrity": "sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==",
"license": "MIT",
"funding": {
"type": "github",
"url": "https://github.com/sponsors/kossnocorp"
}
},
"node_modules/debug": {
"version": "4.4.3",
"resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -2839,9 +2829,9 @@
}
},
"node_modules/follow-redirects": {
"version": "1.15.11",
"resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz",
"integrity": "sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==",
"version": "1.16.0",
"resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
"integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
"funding": [
{
"type": "individual",
@@ -5242,12 +5232,6 @@
"node": ">= 12.13.0"
}
},
"node_modules/reflect-metadata": {
"version": "0.2.2",
"resolved": "https://registry.npmjs.org/reflect-metadata/-/reflect-metadata-0.2.2.tgz",
"integrity": "sha512-urBwgfrvVP/eAyXx4hluJivBKzuEbSQs9rKWCrCkbSxNv8mxPcUZKeuoF3Uy4mJl3Lwprp6yy5/39VWigZ4K6Q==",
"license": "Apache-2.0"
},
"node_modules/require-directory": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",