企业官网建设流程全解析

• 后端
• 即时通讯

用户信息的获取是微信公众平台开发中最常用的功能之一。本指南围绕 EasyWeChat 3.x 的$app->user用户服务，系统讲解如何基于微信openid获取单个/批量用户信息、拉取关注者列表、修改用户备注以及查询用户所属用户组。读完本文，你将掌握 EasyWeChat 3.x 用户管理 API 的完整调用方式、返回值结构，并理解底层 SDK 对微信接口的封装机制，可直接用于公众号后台的粉丝管理、用户画像等实战场景。

前置约束：以下所有用户信息的获取与更新，都是基于微信的openid，并且该用户必须是已关注当前账号的，其它情况（如未关注、粉丝已取关）可能无法正常使用。

获取用户服务实例

与 EasyWeChat 其它服务一样，用户管理服务通过主入口EasyWeChat\Foundation\Application类获取，这也是 3.x 版本所有服务的统一入口（服务端、用户、网页授权、菜单、素材等均由此分发）。

<?php use EasyWeChat\Foundation\Application; // $options 为公众号配置数组（app_id、secret、token、aes_key 等） $app = new Application($options); $userService = $app->user;

获取到$userService之后，即可调用下述全部用户管理 API。

返回值：Collection 集合对象

EasyWeChat 3.x 的所有 API 返回值均为EasyWeChat\Support\Collection集合对象（参见 3.x 教程汇总）。该类实现了 PHP 预定义接口（如ArrayAccess、Serializable等），因此你可以用多种等价方式访问同一个字段：

$user = $userService->get($openId); $user['nickname']; // 数组方式 $user->nickname; // 属性方式 $user->get('nickname'); // get 方法

此外还提供这些便捷操作：检查属性是否存在$user->has('email')、统计元素个数$user->count()、转为数组$user->toArray()、生成 JSON$user->toJSON()等。这也是下文所有代码示例中"既可以用->又可以用[]访问字段"的原因。

获取用户信息

获取单个用户

$user = $userService->get($openId); echo $user->nickname; // 或 $user['nickname']

get($openId)接收一个openid，返回该用户的信息集合，常用的字段包括nickname（昵称）、headimgurl（头像）、sex（性别）、country/province/city（地域）、subscribe（是否关注）、subscribe_time（关注时间）等。

批量获取多个用户

$users = $userService->batchGet([$openId1, $openId2, ...]);

batchGet($openIds)接收一个openid数组，一次请求最多可查询 100 个用户，适用于需要批量同步粉丝资料的场景（例如配合用户列表分页拉取后逐批补齐详细信息）。

获取用户列表

$users = $userService->lists($nextOpenId = null); // $nextOpenId 可选

lists()用于分页拉取当前公众号的全部关注者openid（注意：只返回openid，不含昵称头像等详情，详情需再调用get或batchGet）。$nextOpenId为上一次调用返回的游标，用于翻页取下一批数据；首次调用可省略。

示例：

$users = $userService->lists(); // result { "total": 2, "count": 2, "data": { "openid": [ "", "OPENID1", "OPENID2" ] }, "next_openid": "NEXT_OPENID" } $users->total; // 2

返回结构字段说明：

典型的分页全量拉取写法是"while 循环 +next_openid游标"：先lists()拿到第一页与next_openid，将next_openid传给下一次lists($nextOpenId)，直到返回的next_openid为空，即表示全部关注者已拉取完毕。

修改用户备注

$userService->remark($openId, $remark); // 成功返回 boolean

为指定openid的用户设置备注名，常用于后台人工打标后的备注同步。备注名称长度限制为 30 个字符以内。示例：

$userService->remark($openId, "僵尸粉");

调用成功后返回布尔值true，失败时返回false。需要注意的是，该接口本质上调用的是微信官方"设置用户备注名"接口，只有已关注用户才能设置成功。

获取用户所属用户组 ID

$userService->group($openId);

查询指定openid用户当前所属的用户组 ID（老版公众号的"用户分组"体系），返回值为数字类型的groupId。示例：

$userGroupId = $userService->group($openId);

拿到$userGroupId后，可以进一步用于用户分组的移动、批量管理等操作。需要说明的是：微信官方已将"用户分组"体系逐步演进为"用户标签"体系，两者在 EasyWeChat 中分别对应独立的服务。

用户标签与用户分组

用户管理不仅仅只有信息查询，还涉及精细化运营的两大工具：

• 用户标签：基于标签对粉丝进行多维打标，支持标签的增删改查、给用户打标签/取消标签、按标签拉取用户列表等，是当前微信推荐的分层运营方式；
• 用户分组：老版"用户分组"接口，支持创建/删除/修改分组、移动用户到指定分组、批量移动等操作。

更完整的用户管理能力（例如黑名单拉黑/取消拉黑、openid 迁移转换等）可参考新版文档 official-account/user，新版 API 将其扩展为select（批量获取）、list（列表）、block/unblock（拉黑/取消拉黑）、blacklist（黑名单）、changeOpenid（账号迁移 openid 转换）等更丰富的方法。

与网页授权的配合：openid 从哪来

上文所有接口都依赖openid，而获取用户openid最常用的途径就是网页授权（OAuth）。在 EasyWeChat 3.x 中通过$app->oauth完成授权后，返回的用户对象中$user->id即是微信的OPENID（参见 3.x 网页授权文档）：

$user = $app->oauth->user(); $user->getId(); // 对应微信的 OPENID $user->getNickname(); // 对应微信的 nickname $user->getAvatar(); // 头像网址 $user->getOriginal(); // 原始 API 返回的全部信息

注意：当scope为snsapi_base时，$oauth->user()对象里只有id（即 openid），没有昵称头像等其它信息；需要完整资料时请使用snsapi_userinfo授权。拿到 openid 后，即可配合本文的get/batchGet接口获取更详细的粉丝资料。

底层机制：SDK 如何调用微信接口

虽然 3.x 的user服务在代码层面直接封装了微信cgi-bin/user/info、cgi-bin/user/info/batchget、cgi-bin/user/get、cgi-bin/user/info/updateremark等接口，但理解当前仓库（新版 EasyWeChat）的底层封装逻辑，有助于你推断 3.x 的实现原理与排错方向：

• 统一入口分发：3.x 通过Application的魔术方法__get将$app->user分发到对应服务类；新版仓库中这一设计演变为显式的服务容器，参见 src/OfficialAccount/Application.php 中getServer、getAccessToken、getOAuth等服务初始化方法。
• HTTP 客户端与 Token 注入：新版所有公众号 API 均走统一的AccessTokenAwareClient（src/Kernel/HttpClient/AccessTokenAwareClient.php），自动为请求附加access_token，并以errcode非 0 作为失败判定（src/OfficialAccount/Application.php）；同时基于https://api.weixin.qq.com/的base_uri（src/OfficialAccount/Application.php）拼接用户管理各接口路径。3.x 的 user 服务在调用微信接口前同样会先经 access_token 中间件注入令牌，token 过期时会自动刷新重试。
• AccessToken 的获取与刷新：无论是 3.x 还是新版，access_token 都通过app_id+secret换取，并由缓存组件管理有效期，避免每次请求都向微信换取新令牌；相关实现可对照 src/OfficialAccount/AccessToken.php 与 src/Kernel/HttpClient/AccessTokenExpiredRetryStrategy.php。

因此，当你调用get、batchGet、lists、remark、group返回异常时，排查顺序建议为：先确认配置的app_id/secret是否正确、access_token 是否有效，再确认目标openid是否真实关注了当前公众号（未关注用户会返回错误码，例如 40003 非法 openid）。

总结

本指南完整覆盖了 EasyWeChat 3.x 用户管理的五类核心操作：

1. get($openId)/batchGet($openIds)：单条/批量获取用户详细信息；
2. lists($nextOpenId = null)：分页拉取全部关注者 openid（游标翻页）；
3. remark($openId, $remark)：修改用户备注；
4. group($openId)：查询用户所属用户组 ID；
5. 配合 用户标签、用户分组 完成精细化用户运营。

所有返回值均为Collection集合，既支持->属性访问也支持[]下标访问。只要保证 openid 正确且用户已关注，即可在公众号后台稳定地获取与更新用户信息。

• 后端
• 即时通讯