人称外号大脸猫
首页 博客 关于我

Laravel 开发：快速对接微信公众号初始篇的实战指南

在如今的 Web 开发中，对接微信生态已成为许多项目的标配需求，无论是实现微信支付、微信登录，还是搭建微信公众号互动功能，都需要与微信接口进行深度整合。本文将带你一步步实现 Laravel 框架与微信公众号的对接，从环境搭建到消息处理，让你快速上手微信公众号开发。

微信公众号文档 官方已更新

开发指南

微信公众号文档已更新

准备工作：安装微信公众号 SDK

对接微信公众号的第一步，是引入合适的开发工具包。这里推荐使用w7corp/easywechat，它是一款功能全面的微信 SDK，能极大简化微信接口的调用流程。

通过 Composer 安装 SDK：

composer require w7corp/easywechat

安装完成后，我们就可以基于这个 SDK 构建 Laravel 与微信公众号的交互逻辑了。

核心实现：配置路由与控制器

  1. 定义路由

首先在routes/web.php中添加一个用于接收微信服务器通知的路由：

Route::any('wechat-official-notify', [WeChatOfficialAccountController::class, 'serve'])->name('wechat-official-notify');

这里使用any方法是因为微信服务器会使用 GET 请求进行验证，使用 POST 请求发送消息，所以需要同时支持两种请求方式。

  1. 创建控制器 接下来创建对应的控制器WeChatOfficialAccountController.php，并实现serve方法：
public function serve(WeChatOfficialAccountService $weChatOfficialAccountService)
{
    return $weChatOfficialAccountService->serve();
}

控制器采用了依赖注入的方式引入服务类，将具体的业务逻辑封装在服务类中，符合 Laravel 的最佳实践。

  1. 实现服务类 服务类WeChatOfficialAccountService是对接微信公众号的心，负责初始化 SDK、处理消息交互等功能：
<?php
namespace App\Services;

use AllowDynamicProperties;
use EasyWeChat\Kernel\Contracts\AccessToken;
use EasyWeChat\Kernel\Contracts\RefreshableAccessToken;
use EasyWeChat\Kernel\Exceptions\BadRequestException;
use EasyWeChat\Kernel\Exceptions\InvalidArgumentException;
use EasyWeChat\Kernel\Exceptions\RuntimeException;
use EasyWeChat\Kernel\HttpClient\AccessTokenAwareClient;
use EasyWeChat\OfficialAccount\Application;
use Illuminate\Support\Facades\Log;
use ReflectionException;
use Throwable;

#[AllowDynamicProperties]
class WeChatOfficialAccountService
{
    public function __construct()
    {
        $config = [
            'app_id' => '',
            'secret' => '',
            'token' => '',
            'aes_key' => '',
            'use_stable_access_token' => false,
            'log' => [
                'level' => 'debug',
                'file' => storage_path('logs/wechat.log'),
            ],
        ];
        try {
            $this->app = new Application($config);
        } catch (InvalidArgumentException $e) {
            Log::channel('wechat')->info($e->getMessage());
        }
    }


    public function serve()
    {
        try {
            $server = $this->app->getServer();
            
            return $server->serve();
        } catch (InvalidArgumentException|ReflectionException|Throwable|BadRequestException|InvalidArgumentException|RuntimeException $e) {
            abort(500, $e->getMessage());
        }
    }

    public function getClient(): AccessTokenAwareClient
    {
        return $this->app->getClient();
    }

    public function getAccessToken(): AccessToken|RefreshableAccessToken
    {
        return $this->app->getAccessToken();
    }

}

服务类的主要功能包括：

  • 在构造函数中初始化微信 SDK 应用实例
  • 提供serve方法处理微信服务器的请求
  • 封装获取 HTTP 客户端和访问令牌的方法

关键配置：填写公众号参数

上面的代码中，config数组是对接微信公众号的关键，需要填写从微信公众平台获取的账号信息：

[
    /**
     * 账号基本信息，请从微信公众平台/开放平台获取
     */
    'app_id'  => 'your-app-id',         // AppID
    'secret'  => 'your-app-secret',     // AppSecret
    'token'   => 'your-token',          // Token
    'aes_key' => '',                    // EncodingAESKey，兼容与安全模式下请一定要填写！！！

    /**
     * 是否使用 Stable Access Token
     * 默认 false
     * https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/getStableAccessToken.html
     * true 使用 false 不使用
     */
    'use_stable_access_token' => false,

    /**
     * OAuth 配置
     *
     * scopes：公众平台（snsapi_userinfo / snsapi_base），开放平台：snsapi_login
     * redirect_url：OAuth授权完成后的回调页地址
     */
    'oauth' => [
        'scopes'   => ['snsapi_userinfo'],
        'redirect_url' => '/examples/oauth_callback.php',
    ],

    /**
     * 接口请求相关配置，超时时间等
     */
    'http' => [
        'timeout' => 5.0,
        'retry' => true, // 使用默认重试配置
    ],
]

这些参数的获取方式：

  • app_id和secret：在微信公众号后台的 "开发 - 基本配置" 中获取
  • token：可自行定义，用于验证服务器地址的有效性
  • aes_key：在需要消息加密时使用，可在公众号后台生成

公众号后台配置

完成代码编写后，还需要在微信公众号后台进行配置，使微信服务器能正确将消息推送到我们的应用。

  1. 登录微信公众号后台
  2. 进入路径：设置与开发 =》开发接口管理 =》 服务器配置 =》 服务器地址
  3. 填写服务器地址：即我们定义的路由地址，例如https://www.example.com/wechat-official-notify
  4. 填写配置参数：
    • 服务器地址：填写路由地址，例如https://www.example.com/wechat-official-notify
    • AppID：填写配置中的app_id
    • AppSecret：填写配置中的secret
    • EncodingAESKey：填写配置中的aes_key
    • Token：填写配置中的token
  5. 选择消息加解密方式：建议选择兼容模式
  6. 点击 "启用" 完成配置

开发测试技巧

在开发阶段，推荐使用微信公众平台测试号进行调试，测试号申请地址：https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login 测试号配置与正式号类似，功能接口齐全，更适合开发测试使用。

消息回复实现

对接公众号的核心功能之一是消息回复，EasyWeChat 提供了灵活的消息处理机制，推荐使用中间件模式：

#在 WeChatOfficialAccountService.php 中的serve方法
public function serve()
{
    try {
        $server = $this->app->getServer();
        $server->with(MyCustomHandler::class);
        return $server->serve();
    } catch (InvalidArgumentException|ReflectionException|Throwable|BadRequestException|InvalidArgumentException|RuntimeException $e) {
        abort(500, $e->getMessage());
    }
}

class MyCustomHandler
{
    public function __invoke($message, \Closure $next)
    {
        if ($message->MsgType === 'text') {
            // 处理文本消息
            return "你发送的文本是：{$message->Content}";
        }

        return $next($message);
    }
}

除了中间件模式，还可以通过注册指定消息类型的处理器来处理消息： 通过 EasyWeChat SDK 的addMessageListener方法注册事件处理器，实现微信公众号关注事件的自动化响应

处理普通消息

// 处理文本消息
$server->addMessageListener('text', function($message) {
    return "收到文本消息：{$message->Content}";
});

// 处理图片消息
$server->addMessageListener('image', function($message) {
    return new \EasyWeChat\OfficialAccount\Message\Image($message->MediaId);
});

处理事件消息

// 处理关注事件
$server->addMessageListener('subscribe', function($message) {
    return "欢迎关注我的公众号！";
});

// 处理菜单点击事件
$server->addMessageListener('click', function($message) {
    switch ($message->EventKey) {
        case 'menu_1':
            return "你点击了菜单1";
        default:
            return "未知菜单";
    }
});

总结

通过本文的步骤，我们完成了 Laravel 与微信公众号的基础对接，包括环境搭建、配置实现、消息处理等核心功能。在实际开发中，还可以基于这个基础扩展更多功能，如微信支付、模板消息、自定义菜单等。 EasyWeChat SDK 提供了丰富的 API，建议参考其官方文档深入学习，以便更好地利用 SDK 开发出强大的微信公众号功能。 希望本文能帮助你快速上手 Laravel 对接微信公众号的开发，祝你的项目开发顺利！

copyright ©2025 ahimu.com all rights reserved 皖ICP备19021547号-1