QQ快捷登录API

API地址：https://auth.6eu.cn/api/connect.php

开发语言：PHP

适用场景：个人自研项目、商城、记账系统、后台管理系统快速接入QQ快捷登录

文档简介

快捷QQ登录API，是一套封装好的QQ OAuth快捷登录服务，专门用于网站接入QQ一键登录。

很多自研项目接入QQ原生登录时，会遇到密钥暴露、接口格式不统一、回调处理繁琐等问题。本API把QQ授权流程封装在服务端，保护密钥，对外提供统一接口，同时兼容新旧两套调用方式，老项目无需大规模改造。

核心特点：

• 密钥存放于服务端，前端无法获取，提升安全性；
• 对外提供两套接口规范，新项目新版接口、存量项目沿用旧接口，平滑迁移；
• 统一处理网络异常、JSON解析、跨域、输出缓冲区污染等PHP接口常见问题；
• 回调返回用户信息增加MD5签名校验，防止数据篡改。

本API为无状态服务，不会持久化存储用户个人信息，仅在授权流程临时处理授权信息。

整体调用流程

1. 业务前端请求API，获取QQ授权登录地址；
2. 用户跳转至QQ授权页面，完成账号授权；
3. QQ授权回调到本API地址，API接收code与state参数，向QQ服务换取用户凭证；
4. API处理返回数据，提供两种返回模式：
   • 新版接口：校验state，验证成功后直接JSON返回access_token、social_uid；state参数必须原封不动随回调带回，否则校验失败
   • 旧版兼容模式：打包用户信息+MD5签名生成token，302重定向回业务站点。

调用链路：业务前端 ↔ QQ快捷登录API（auth.6eu.cn） ↔ QQ OAuth服务

环境部署要求

• PHP版本 ≥7.0，必须启用CURL扩展；
• 文件部署路径：/api/connect.php；
• 域名配置：auth.6eu.cn，配置DNS解析，强制HTTPS（QQ OAuth强制要求HTTPS回调）；
• 服务器：国内服务器需要完成ICP备案。

安全提示：Python和JAVA项目可能会有问题。

接口总览

基础请求地址：https://auth.6eu.cn/api/connect.php
请求方式：GET
字符编码：UTF-8
跨域：自带CORS跨域头，支持前端AJAX调用，自动处理OPTIONS预检请求

接口详细说明

1. 新版接口 act=login（获取授权跳转链接）

推荐新项目使用，拿到授权地址后直接跳转QQ登录页面。接口会自动生成state参数附加到QQ授权链接。

GET https://auth.6eu.cn/api/connect.php?act=login

返回结果

• 成功：HTTP 302重定向，Location为QQ官方授权页面；
• 失败：返回JSON格式错误信息

{
    "error_code": -1,
    "error_msg": "缺少redirect_uri参数"
}

2. 新版接口 act=callback（QQ回调入口，Code换取用户信息）

此接口是QQ授权回调专用地址，由QQ服务自动GET请求，不要前端手动调用。

QQ用户授权完成后，会自动回调访问这个接口，携带code和state参数。接口会校验state一致性，校验通过后请求QQ服务拿到用户信息，返回JSON。

GET https://auth.6eu.cn/api/connect.php?act=callback

✅成功返回示例

{
    "access_token": "xxxx",
    "social_uid": "12345678",
    "media_type": "qq"
}

❌失败返回示例（你测试遇到的未知错误）

{
    "error_code": "43D881A306A52ADFCDEF3AFF41381A5F",
    "error_msg": "未知错误"
}

3. 旧版兼容接口 action=getLoginUrl

存量老项目使用，仅返回登录链接JSON，不会自动跳转

GET https://auth.6eu.cn/api/connect.php?action=getLoginUrl

成功返回

{
    "code": 0,
    "msg": "success",
    "url": "https://xxx QQ授权地址"
}

4. 旧版兼容接口 action=getUserInfo

使用回调带回的加密token，校验MD5签名，解密获取完整用户信息

GET https://auth.6eu.cn/api/connect.php?action=getUserInfo

成功返回

{
    "code": 0,
    "data": {
        //QQ返回的完整用户信息
    }
}

5. 老项目兼容回调入口

调用示例：https://auth.6eu.cn/api/connect.php?code=xxx

无act/action参数，仅携带code。
API自动请求QQ授权接口换取用户信息，使用AppKey生成MD5签名打包token，302重定向到业务回调地址，URL参数携带token=。业务系统读取token，调用getUserInfo接口解析用户资料。

返回码规范

前端业务对接示例 JS

// 获取QQ登录地址，触发登录跳转
async function getQQLoginUrl(){
    //替换成你的业务回调页面地址
    const callbackUrl = "https://你的网站/login/callback";
    const api = `https://auth.6eu.cn/api/connect.php?action=getLoginUrl&redirect=${encodeURIComponent(callbackUrl)}`;
    const res = await fetch(api);
    const data = await res.json();
    if(data.code === 0){
        window.location.href = data.url;
    }
}

核心设计亮点

• 输出缓冲区清理
  循环清空PHP所有ob缓冲区，彻底消除BOM头、多余换行、空格污染，保证JSON输出纯净，解决PHP接口最常见的JSON格式报错坑。
• 完整异常捕获
  CURL网络错误、SSL异常、HTTP非200状态码、非标准JSON返回全部捕获，统一返回可读错误信息，方便线上排查。
• 双接口体系
  新旧两套接口并存，新项目使用act体系，存量老项目继续用action接口，平滑升级，业务代码无需一次性全部改造。
• 签名校验
  旧版token使用用户信息+AppKey做MD5签名，防止token被篡改，保证回调数据可信。
• 密钥隔离
  QQ应用AppID/AppKey保存在服务端，前端永远看不到密钥，避免直接暴露凭证带来的安全风险。

故障排查手册（重点新增你遇到的未知错误）

• 登录失败，error_msg="未知错误"
  常见原因：①state参数丢失或者前后不一致；②code已经使用过，code一次性失效；③QQ互联后台配置的回调域名与实际访问域名不匹配；④QQ互联应用权限/审核未通过。优先检查state传递。
• curl请求失败
  服务器未安装php-curl扩展；服务器出站网络限制，无法访问QQ授权接口。
• JSON返回格式异常
  一般是文件BOM头、代码多余输出；代码自带缓冲区清理，若仍出现，编辑器保存选择UTF-8无BOM编码。
• QQ授权页面返回403
  QQ互联后台回调域名未添加白名单，或者AppID/AppKey配置错误。
• Token签名校验失败
  API配置的AppKey，和生成token时使用的AppKey不一致。
• 回调跳转无code返回
  检查回调地址是否为HTTPS，QQ OAuth不支持HTTP回调地址。

结语

这套QQ快捷登录API目前已经部署并在我的多个自研项目稳定运行，记账系统、商城后台均接入使用。

把QQ OAuth登录封装成独立服务最大好处：业务代码和QQ授权逻辑解耦。后续QQ登录规则、接口发生变更，只需要修改这一处API，前端、业务后端代码完全不用改动。

后续规划：基于接口返回的social_uid，新增独立接口获取QQ昵称、头像信息。

分享到：

打赏 生成海报