@sansenjian/qq-music-api 2.2.7 → 2.2.10

package/CHANGELOG.md

@@ -1,4 +1,26 @@
-## 2.2.7 (2026-03-08)
+## 2.2.10 (2026-03-14)
+
+
+
+## 2.2.10 (2026-03-14)
+
+
+### Bug Fixes
+
+* stabilize lyric flow and refresh CI/Vercel config ([#13](https://github.com/sansenjian/qq-music-api/issues/13)) ([34ed7b1](https://github.com/sansenjian/qq-music-api/commit/34ed7b164fa74e12d753867b5a7b49d3b5bf0200))
+
+
+
+## 2.2.9 (2026-03-14)
+
+
+### Bug Fixes
+
+* rewrite getMusicPlay url logic ([#12](https://github.com/sansenjian/qq-music-api/issues/12)) ([ec9823b](https://github.com/sansenjian/qq-music-api/commit/ec9823be7821f6c83427f1aada8848729936e1d2))
+
+
+
+## 2.2.8 (2026-03-08)
 
 
 

package/README.md

@@ -9,6 +9,8 @@
 ![node](https://img.shields.io/badge/node-%3E%3D20.0.0-green?style=flat-square)
 <br />
 ![GitHub repo size](https://img.shields.io/github/repo-size/sansenjian/qq-music-api?style=flat-square) ![GitHub package.json version](https://img.shields.io/github/package-json/v/sansenjian/qq-music-api?style=flat-square) ![GitHub](https://img.shields.io/github/license/sansenjian/qq-music-api?style=flat-square) ![GitHub open issues](https://img.shields.io/github/issues/sansenjian/qq-music-api?style=flat-square) ![GitHub closed issues](https://img.shields.io/github/issues-closed/sansenjian/qq-music-api) ![GitHub last commit](https://img.shields.io/github/last-commit/sansenjian/qq-music-api?style=flat-square) ![GitHub top language](https://img.shields.io/github/languages/top/sansenjian/qq-music-api?style=flat-square)
+<br />
+[![Codecov](https://img.shields.io/codecov/c/github/sansenjian/qq-music-api?style=flat-square&logo=codecov)](https://codecov.io/gh/sansenjian/qq-music-api)
 
 </div>
 

package/dist/api/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const koaApp_1 = __importDefault(require("../koaApp"));
+const handler = koaApp_1.default.callback();
+exports.default = handler;
+module.exports = handler;

package/dist/app.js

@@ -4,55 +4,40 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 require("reflect-metadata");
-const koa_1 = __importDefault(require("koa"));
-const koa_bodyparser_1 = __importDefault(require("koa-bodyparser"));
-const path_1 = __importDefault(require("path"));
-const koa_static_1 = __importDefault(require("koa-static"));
 const chalk_1 = __importDefault(require("chalk"));
-const koa_cors_1 = __importDefault(require("./middlewares/koa-cors"));
-const router_1 = __importDefault(require("./routers/router"));
-const cookie_1 = __importDefault(require("./util/cookie"));
 const colors_1 = __importDefault(require("./util/colors"));
-const user_info_1 = __importDefault(require("./config/user-info"));
+const service_config_1 = __importDefault(require("./config/service-config"));
 const package_json_1 = __importDefault(require("./package.json"));
-const app = new koa_1.default();
-global.userInfo = user_info_1.default;
-console.log(chalk_1.default.green('\n🥳🎉 We had supported config the user cookies. \n'));
+const koaApp_1 = __importDefault(require("./koaApp"));
+// 输出服务配置信息
+console.log(chalk_1.default.green('\n🎵 QQ Music API Service Starting...\n'));
 console.log(colors_1.default.info(`Current Version: ${package_json_1.default.version}`));
-if (!(global.userInfo.loginUin || global.userInfo.uin)) {
-    console.log(chalk_1.default.yellow(`😔 The configuration ${chalk_1.default.red('loginUin')} or your ${chalk_1.default.red('cookie')} in file ${chalk_1.default.green('config/user-info')} has not configured. \n`));
+console.log(colors_1.default.info(`Fallback Mode: ${service_config_1.default.fallbackMode ? 'Enabled' : 'Disabled'}`));
+console.log(colors_1.default.info(`Use Global Cookie: ${service_config_1.default.useGlobalCookie ? 'Yes' : 'No'}`));
+if (service_config_1.default.fallbackMode) {
+    console.log(chalk_1.default.green('\n✅ 降级模式已启用：支持手动传递 Cookie\n'));
+    console.log('使用方式:');
+    console.log('  1. Query 参数：GET /api/endpoint?cookie=your_cookie');
+    console.log('  2. Header: X-Custom-Cookie: your_cookie');
+    console.log('  3. Header: Cookie: your_cookie\n');
 }
-if (!global.userInfo.cookie) {
-    console.log(chalk_1.default.yellow(`😔 The configuration ${chalk_1.default.red('cookie')} in file ${chalk_1.default.green('config/user-info')} has not configured. \n`));
+if (!service_config_1.default.useGlobalCookie) {
+    console.log(chalk_1.default.yellow('\n⚠️  全局 Cookie 未启用：需要登录的接口请手动传递 Cookie\n'));
+}
+if (service_config_1.default.useGlobalCookie) {
+    console.log(chalk_1.default.green('\n✅ 全局 Cookie 已启用\n'));
+    if (!(global.userInfo.loginUin || global.userInfo.uin)) {
+        console.log(chalk_1.default.yellow(`😔 The configuration ${chalk_1.default.red('loginUin')} or your ${chalk_1.default.red('cookie')} in file ${chalk_1.default.green('config/user-info')} has not configured. \n`));
+    }
+    if (!global.userInfo.cookie) {
+        console.log(chalk_1.default.yellow(`😔 The configuration ${chalk_1.default.red('cookie')} in file ${chalk_1.default.green('config/user-info')} has not configured. \n`));
+    }
 }
-app.use((0, koa_bodyparser_1.default)());
-app.use((0, cookie_1.default)());
-app.use((0, koa_static_1.default)(path_1.default.join(__dirname, 'public')));
-// logger
-app.use(async (ctx, next) => {
-    await next();
-    const rt = ctx.response.get('X-Response-Time');
-    console.log(colors_1.default.prompt(`${ctx.method} ${ctx.url} - ${rt}`));
-});
-// cors
-app.use((0, koa_cors_1.default)({
-    origin: ctx => ctx.request.header?.origin || '*',
-    exposeHeaders: ['WWW-Authenticate', 'Server-Authorization'],
-    maxAge: 5,
-    credentials: true,
-    allowMethods: ['GET', 'POST', 'DELETE'],
-    allowHeaders: ['Content-Type', 'Authorization', 'Accept'],
-}));
-// x-response-time
-app.use(async (ctx, next) => {
-    const start = Date.now();
-    await next();
-    const ms = Date.now() - start;
-    ctx.set('X-Response-Time', `${ms}ms`);
-});
-app.use(router_1.default.routes())
-    .use(router_1.default.allowedMethods());
 const PORT = typeof process.env.PORT === 'string' ? parseInt(process.env.PORT, 10) : (process.env.PORT || 3200);
-app.listen(PORT, () => {
-    console.log(colors_1.default.prompt(`server running @ http://localhost:${PORT}`));
-});
+const isMainModule = require.main === module;
+if (isMainModule) {
+    koaApp_1.default.listen(PORT, () => {
+        console.log(colors_1.default.prompt(`server running @ http://localhost:${PORT}`));
+    });
+}
+exports.default = koaApp_1.default;

package/dist/config/service-config.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const configPath = path_1.default.join(__dirname, './service-config.json');
+// 创建默认配置
+const defaultConfig = {
+    fallbackMode: true,
+    useGlobalCookie: false,
+    cookieParamName: 'cookie'
+};
+// 读取或创建配置文件
+let config = defaultConfig;
+if (fs_1.default.existsSync(configPath)) {
+    try {
+        const content = fs_1.default.readFileSync(configPath, 'utf-8');
+        config = { ...defaultConfig, ...JSON.parse(content) };
+    }
+    catch (e) {
+        console.warn('service-config.json 读取失败，使用默认配置');
+        fs_1.default.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2), 'utf-8');
+    }
+}
+else {
+    fs_1.default.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2), 'utf-8');
+}
+// 支持环境变量覆盖
+if (process.env.FALLBACK_MODE === 'true') {
+    config.fallbackMode = true;
+}
+if (process.env.USE_GLOBAL_COOKIE === 'true') {
+    config.useGlobalCookie = true;
+}
+exports.default = config;

package/dist/index.js

@@ -1,3 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-require("./app");
+const app_1 = __importDefault(require("./app"));
+const colors_1 = __importDefault(require("./util/colors"));
+const parsedPort = Number.parseInt(process.env.PORT ?? '', 10);
+const PORT = Number.isFinite(parsedPort) ? parsedPort : 3200;
+if (require.main === module) {
+    app_1.default.listen(PORT, () => {
+        console.log(colors_1.default.prompt(`server running @ http://localhost:${PORT}`));
+    });
+}
+exports.default = app_1.default;

package/dist/jest.config.js

@@ -8,12 +8,22 @@ const config = {
         'module/**/*.ts',
         'routers/**/*.ts',
         'util/**/*.ts',
+        'middlewares/**/*.ts',
         '!**/node_modules/**',
         '!**/tests/**',
-        '!**/dist/**'
+        '!**/dist/**',
+        '!**/*.d.ts',
+        '!**/types/**/*.ts'
     ],
     coverageDirectory: 'coverage',
-    coverageReporters: ['text', 'lcov', 'html'],
+    coverageReporters: ['text', 'lcov', 'html', 'json-summary', 'json'],
+    coveragePathIgnorePatterns: [
+        '/node_modules/',
+        '/tests/',
+        '/dist/',
+        '\\.d\\.ts$',
+        '/types/'
+    ],
     coverageThreshold: {
         global: {
             branches: 35,
@@ -26,6 +36,8 @@ const config = {
     modulePathIgnorePatterns: ['<rootDir>/dist/'],
     testTimeout: 10000,
     verbose: true,
+    collectCoverage: true, // 默认开启覆盖率
+    coverageProvider: 'v8', // 使用 v8 引擎，更准确
     moduleNameMapper: {
         '^@module/(.*)$': '<rootDir>/module/$1',
         '^@routers/(.*)$': '<rootDir>/routers/$1',

package/dist/koaApp.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const koa_1 = __importDefault(require("koa"));
+const koa_bodyparser_1 = __importDefault(require("koa-bodyparser"));
+const path_1 = __importDefault(require("path"));
+const koa_static_1 = __importDefault(require("koa-static"));
+const koa_cors_1 = __importDefault(require("./middlewares/koa-cors"));
+const router_1 = __importDefault(require("./routers/router"));
+const cookie_1 = __importDefault(require("./util/cookie"));
+const fallback_middleware_1 = __importDefault(require("./middlewares/fallback-middleware"));
+const colors_1 = __importDefault(require("./util/colors"));
+const user_info_1 = __importDefault(require("./config/user-info"));
+const app = new koa_1.default();
+global.userInfo = user_info_1.default;
+app.use((0, koa_bodyparser_1.default)());
+app.use((0, fallback_middleware_1.default)());
+app.use((0, cookie_1.default)());
+app.use((0, koa_static_1.default)(path_1.default.join(__dirname, 'public')));
+// logger
+app.use(async (ctx, next) => {
+    await next();
+    const rt = ctx.response.get('X-Response-Time');
+    console.log(colors_1.default.prompt(`${ctx.method} ${ctx.url} - ${rt}`));
+});
+// cors
+app.use((0, koa_cors_1.default)({
+    origin: ctx => ctx.request.header?.origin || '*',
+    exposeHeaders: ['WWW-Authenticate', 'Server-Authorization'],
+    maxAge: 5,
+    credentials: true,
+    allowMethods: ['GET', 'POST', 'DELETE'],
+    allowHeaders: ['Content-Type', 'Authorization', 'Accept'],
+}));
+// x-response-time
+app.use(async (ctx, next) => {
+    const start = Date.now();
+    await next();
+    const ms = Date.now() - start;
+    ctx.set('X-Response-Time', `${ms}ms`);
+});
+app.use(router_1.default.routes()).use(router_1.default.allowedMethods());
+exports.default = app;

package/dist/middlewares/fallback-middleware.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const service_config_1 = __importDefault(require("../config/service-config"));
+const cookieResolver_1 = require("../util/cookieResolver");
+/**
+ * 降级模式中间件：支持通过 query/header 手动传递 Cookie。
+ */
+const fallbackMiddleware = () => async (ctx, next) => {
+    if (!service_config_1.default.fallbackMode) {
+        await next();
+        return;
+    }
+    const { cookie, source } = (0, cookieResolver_1.resolveRequestCookie)(ctx, {
+        fallbackMode: true,
+        useGlobalCookie: false,
+        cookieParamName: service_config_1.default.cookieParamName
+    });
+    if (cookie) {
+        (0, cookieResolver_1.setRequestCookieContext)(ctx, cookie);
+        if (process.env.DEBUG === 'true') {
+            console.log(`[FallbackMode] use cookie from ${source}, length: ${cookie.length}`);
+        }
+    }
+    await next();
+};
+exports.default = fallbackMiddleware;

package/dist/module/apis/music/getLyric.js

@@ -4,29 +4,233 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const lyricParse_1 = require("../../../util/lyricParse");
-const request_1 = __importDefault(require("../../../util/request"));
-const apiResponse_1 = require("../../../util/apiResponse");
+const y_common_1 = __importDefault(require("../y_common"));
+const cookieResolver_1 = require("../../../util/cookieResolver");
+const UCommon_1 = __importDefault(require("../UCommon/UCommon"));
+const MUSICU_TIMEOUT_MS = 10000;
+const getCookieFromOptions = (option) => {
+    if (!option || typeof option !== 'object') {
+        return undefined;
+    }
+    const headers = option.headers;
+    if (!headers || typeof headers !== 'object') {
+        return undefined;
+    }
+    const cookie = headers.Cookie || headers.cookie;
+    return typeof cookie === 'string' ? cookie : undefined;
+};
+const resolveUin = (cookie) => {
+    return (0, cookieResolver_1.extractUinFromCookie)(cookie) || String(global.userInfo?.loginUin || '0');
+};
+const decodeLyricField = (value) => {
+    if (typeof value !== 'string' || !value) {
+        return '';
+    }
+    try {
+        const decoded = Buffer.from(value, 'base64').toString();
+        return decoded || value;
+    }
+    catch {
+        return value;
+    }
+};
+const normalizeLyricResponse = (resData, isFormat) => {
+    const lyricString = decodeLyricField(resData?.lyric);
+    const lyric = isFormat && lyricString ? (0, lyricParse_1.lyricParse)(lyricString) : lyricString;
+    return {
+        ...resData,
+        lyric
+    };
+};
+const hasNegativeBizCode = (data) => {
+    const codes = [data?.retcode, data?.code, data?.subcode]
+        .map(item => Number(item))
+        .filter(item => !Number.isNaN(item));
+    return codes.some(item => item < 0);
+};
+const normalizeSongId = (value) => {
+    const id = Number(value);
+    if (Number.isFinite(id) && id > 0) {
+        return String(id);
+    }
+    return undefined;
+};
+const mergePrimaryAndFallbackPayload = (primaryPayload, fallbackPayload) => {
+    const merged = {
+        ...primaryPayload,
+        ...fallbackPayload
+    };
+    // When fallback succeeds but does not include status fields, force success codes
+    // to avoid preserving negative primary codes in response.
+    if (!Object.prototype.hasOwnProperty.call(fallbackPayload, 'retcode')) {
+        merged.retcode = 0;
+    }
+    if (!Object.prototype.hasOwnProperty.call(fallbackPayload, 'code')) {
+        merged.code = 0;
+    }
+    if (!Object.prototype.hasOwnProperty.call(fallbackPayload, 'subcode')) {
+        merged.subcode = 0;
+    }
+    return merged;
+};
+const resolveSongIdBySongmid = async ({ songmid, loginUin }) => {
+    const response = await (0, UCommon_1.default)({
+        method: 'get',
+        params: {
+            format: 'json',
+            data: {
+                comm: {
+                    uin: loginUin,
+                    ct: 24,
+                    cv: 0
+                },
+                songinfo: {
+                    method: 'get_song_detail_yqq',
+                    param: {
+                        song_type: 0,
+                        song_mid: songmid,
+                        song_id: 0
+                    },
+                    module: 'music.pf_song_detail_svr'
+                }
+            }
+        },
+        option: {}
+    });
+    const data = (response?.data || {});
+    return normalizeSongId(data?.songinfo?.data?.track_info?.id ||
+        data?.songinfo?.data?.trackInfo?.id ||
+        data?.track_info?.id);
+};
+const fetchLyricByMusicu = async ({ songmid, songid, loginUin, cookie }) => {
+    const reqPayload = {
+        req_0: {
+            module: 'music.musichallSong.PlayLyricInfo',
+            method: 'GetPlayLyricInfo',
+            param: {
+                songMID: songmid || '',
+                songID: Number(songid || 0),
+                trans_t: 0,
+                roma_t: 0,
+                qrc_t: 0,
+                crypt: 1,
+                lrc_t: 0,
+                interval: 0
+            }
+        },
+        loginUin,
+        comm: {
+            uin: loginUin,
+            format: 'json',
+            ct: 24,
+            cv: 0
+        }
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), MUSICU_TIMEOUT_MS);
+    const headers = {
+        'Content-Type': 'application/json',
+        Referer: 'https://y.qq.com/portal/player.html',
+        Origin: 'https://y.qq.com'
+    };
+    if (cookie) {
+        headers.Cookie = cookie;
+    }
+    const response = await (async () => {
+        try {
+            return await fetch('https://u.y.qq.com/cgi-bin/musicu.fcg', {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(reqPayload),
+                signal: controller.signal
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    })();
+    const raw = await response.text();
+    const upstream = JSON.parse(raw || '{}');
+    return (upstream?.req_0?.data || upstream?.PlayLyricInfo?.data || {});
+};
 exports.default = async ({ method = 'get', params = {}, option = {}, isFormat = false }) => {
+    const cookie = getCookieFromOptions(option);
+    const loginUin = resolveUin(cookie);
+    const songmid = typeof params.songmid === 'string'
+        ? params.songmid
+        : undefined;
+    const songid = typeof params.songid === 'string'
+        ? params.songid
+        : undefined;
     const data = Object.assign(params, {
         format: 'json',
         outCharset: 'utf-8',
-        pcachetime: Date.now()
+        pcachetime: Date.now(),
+        loginUin
     });
     const options = Object.assign(option, {
+        headers: Object.assign({}, option?.headers || {}, {
+            referer: 'https://y.qq.com/portal/player.html',
+            host: 'c.y.qq.com'
+        }),
         params: data
     });
-    return (0, apiResponse_1.handleApi)((0, request_1.default)({
-        url: '/lyric/fcgi-bin/fcg_query_lyric_new.fcg',
-        method: method,
-        options
-    }), {
-        transformData: (resData) => {
-            const lyricString = resData && resData.lyric && Buffer.from(resData.lyric, 'base64').toString();
-            const lyric = isFormat && lyricString ? (0, lyricParse_1.lyricParse)(lyricString) : lyricString;
-            return {
-                ...resData,
-                lyric
-            };
+    try {
+        const primaryResponse = await (0, y_common_1.default)({
+            url: '/lyric/fcgi-bin/fcg_query_lyric_new.fcg',
+            method: method,
+            options
+        });
+        let payload = (primaryResponse?.data || {});
+        if (hasNegativeBizCode(payload)) {
+            try {
+                let fallbackPayload = await fetchLyricByMusicu({
+                    songmid,
+                    songid,
+                    loginUin,
+                    cookie
+                });
+                if (hasNegativeBizCode(fallbackPayload) && !normalizeSongId(songid) && songmid) {
+                    const resolvedSongId = await resolveSongIdBySongmid({ songmid, loginUin });
+                    if (resolvedSongId) {
+                        fallbackPayload = await fetchLyricByMusicu({
+                            songmid,
+                            songid: resolvedSongId,
+                            loginUin,
+                            cookie
+                        });
+                    }
+                }
+                if (Object.keys(fallbackPayload).length > 0 && !hasNegativeBizCode(fallbackPayload)) {
+                    payload = mergePrimaryAndFallbackPayload(payload, fallbackPayload);
+                }
+            }
+            catch {
+                // keep primary payload when fallback request fails
+            }
         }
-    });
+        return {
+            status: 200,
+            body: {
+                response: normalizeLyricResponse(payload, Boolean(isFormat))
+            }
+        };
+    }
+    catch (error) {
+        const normalizedError = error instanceof Error
+            ? {
+                name: error.name,
+                message: error.message
+            }
+            : {
+                name: 'Error',
+                message: 'Internal server error'
+            };
+        return {
+            status: 500,
+            body: {
+                error: normalizedError
+            }
+        };
+    }
 };