全部产品
Search

搜索本产品

    云消息队列 RocketMQ 版：环境准备（v1.x.x）

    文档中心

    云消息队列 RocketMQ 版：环境准备（v1.x.x）

    更新时间：Jun 11, 2026

    本文为您介绍使用C++ SDK接入云消息队列 RocketMQ 版所需完成的准备工作、使用说明以及注意事项，以便后续使用C++ SDK收发消息。

    重要
    • 推荐您使用最新的RocketMQ 5.x系列SDK，5.x系列SDK作为主力研发版本，和云消息队列 RocketMQ 版5.x服务端完全兼容，提供了更全面的功能并支持更多增强特性。更多信息，请参见5.x系列SDK。
    • RocketMQ 4.x/3.x系列SDK和ONS系列SDK后续仅做功能维护，建议仅存量业务使用。

    使用前，请注意以下几点：

    • 本文仅针对C++ SDK v1.x.x版本进行说明。

    • 代码里涉及到的Topic和Group ID，需要到控制台上创建。Message Tag可以完全由应用自定义，具体创建过程请参见创建资源。

    • 使用云消息队列 RocketMQ 版服务的应用程序需要部署在阿里云ECS上。

    SDK下载

    C++ SDK支持Windows和Linux两个操作系统，而且接口完全一致。Linux下支持CentOS 6（RHEL 6）和CentOS 7（RHEL 7）系列。C++ SDK的下载链接，请参见版本说明。

    下载完成后进行解压，会有如下目录结构，各目录的说明如下：

    • demo/（只针对Windows系统）

      包含了一个创建好的Windows C++ 演示Demo。

    • example/

      包含了普通消息发送、Oneway消息发送、顺序消息发送、普通消息消费、顺序消息消费等例子，Linux下还包含了Makefile用于example的编译和管理。

    • include/

      包含了用户自己编写的程序需要的头文件。

    • lib/

      • Linux SDK子目录如下，分别是64位的静态库和动态库。

        lib-boost-share/
  libonsclient4cpp.so
lib-boost-static/
  libonsclient4cpp.a

      • Windows SDK子目录如下，是64位系统下SDK的dll库。如果没有安装Visual Studio 2015环境，需要拷贝安装vc_redist.x64。 这是Visual C++ 2015的运行时环境。

        64/
vc_redist.x64

    • SDK_GUIDE.pdf

      SDK环境准备文档和FAQ。

    • changelog

      新版本发布解决的问题和引入的新特性列表。

    Linux C++ SDK

    自2016年12月02日开始，Linux CPP版本依赖了高性能boost库（1.62.0版本），不仅降低了CPU资源占用率，而且提高了运行效率。目前主要依赖了boost_system、boost_thread、boost_chrono、boost_filesystem四个库，有静态库和动态库两种解决方案。

    静态解决方案

    云消息队列 RocketMQ 版的库文件在lib/lib-boost-static目录下，boost库静态链接到libonsclient4cpp.a中。对于没有依赖boost库的业务方，可以直接选用静态库方案。静态库方案中，相应的boost库已经链接到libonsclient4cpp.a，编译时只需要链接libonsclient4cpp.a即可，无需执行其他操作。使用方式如下。

    cd aliyun-mq-linux-cpp-sdk  //下载的SDK解压后的路径
cd example                  //进入example目录，修改example文件，填入您创建的Topic和Key等相关的信息
make static=1
    重要

    完全的静态链接请确保机器上安装了libstdc++、pthread等相关的静态库。默认安装的libstdc++ 是没有安装静态库的，所以需要通过yum或者apt-get来安装相关的静态库。

    此外使用如上方式会出现一些警告信息如下。

    warning: Using 'gethostbyaddr' in statically linked applications requires at runtime the shared libraries from the glibc version used for linking

    建议最佳的方式，不要使用完全的静态链接，而是只静态链接onsclient4cpp，其他库动态链接即可。使用方式如下。

    g++ -ggdb -Wall -O3 -I../include    ../example/ProducerExampleForEx.cpp  -Wl,-static -lonsclient4cpp -L../lib/lib-boost-static/ -Wl,-Bdynamic  -lpthread -ldl -lrt -o ../example/ProducerExampleForEx

    此外，由于GCC 5.x引入Dual ABI，编译链接时，请添加-D_GLIBCXX_USE_CXX11_ABI=0编译选项。

    动态解决方案

    云消息队列 RocketMQ 版的库文件在lib/lib-boost-share目录下，需要业务方生成可执行文件时链接boost动态库和libonsclient4cpp.so。对于业务方已经依赖了boost库，需要选择动态库方案的情况，对boost库的依赖需要做如下工作：

    1. 下载boost 1.62.0版本。

      boost 1.62.0

    2. 解压boost 1.62.0。

      tar --bzip2 -xf /path/to/boost_1_62_0.tar.bz2

    3. 安装boost 1.62.0版本：

      1. 进入boost 1.62.0解压后的路径：cd path/to/boost_1_62_0

      2. 配置boost：./bootstrap.sh

      3. 编译boost: ./b2 link=shared runtime-link=shared

      4. 安装boost: ./b2 install

    4. 执行ldconfig -v|grep libboost。如果有相关的输出，则表明boost动态库在动态库搜索路径中。

    5. 生成可执行文件时，需要链接boost动态库和云消息队列 RocketMQ 版的动态库。方法如下。

      cd aliyun-mq-linux-cpp-sdk  //下载的SDK解压后的路径
cd example                  //进入example目录，修改example文件，填入自己在消息队列RocketMQ版控制台创建的Topic和Key等相关的信息
g++ -Wall -Wno-deprecated -L ../lib/lib-boost-share/ -I ../include/ ProducerExampleForEx.cpp  -lonsclient4cpp -lboost_system -lboost_thread -lboost_chrono -lboost_filesystem -lpthread
export LD_LIBRARY_PATH="../lib/lib-boost-share/"  //添加动态载入的搜索路径
./a.out  //运行程序

    Windows C++ SDK

    Visual Studio 2015环境下使用C++ SDK

    1. 使用Visual Studio 2015创建自己的项目。在 Visual Studio 2015 中，单击 New Project，在模板树中依次展开 Installed > Templates > Visual C++，选择 Win32，然后在右侧模板列表中选择 Win32 Console Application，设置项目名称后单击 OK 创建项目。在 Win32 Application Wizard - ConsoleApplication1 向导概览页中，确认当前项目类型为 Console application，单击 Next > 进入应用程序设置页面。在 Win32 Application Wizard 的 Application Settings 页面中，将 Application type 设置为 Console application，勾选 Empty project，然后单击 Finish 完成项目创建。

    2. 右键单击项目，选择属性 > 配置管理器，设置活动解决方案配置为release，设置活动解决方案平台为x64。

    3. 右键单击项目，依次选择属性 > 配置属性 > 常规 > 输出目录：/A。按照活动解决方案平台的设置，拷贝64位lib目录下的所有文件到输出目录/A。右键单击项目，依次选择 属性 > 配置属性 > 常规，确认 Output Directory 的值为 $(SolutionDir)$(Platform)\$(Configuration)\（该路径在构建后自动生成），并将 Platform Toolset 设为 Visual Studio 2015 - Windows XP (v140_xp)。将下载的 SDK 的 lib 目录下的 ONSClient4CPP.dll、ONSClient4CPP.lib 和 ONSClient4CPP.pdb 文件拷贝到该输出目录中。

    4. 右键单击项目，依次选择属性 > 配置属性 > C/C++-常规 > 附加包含目录：/B。 拷贝include目录下的头文件到包含目录：/B。

    5. 右键单击项目，依次选择属性 > 配置属性 > 链接 > 常规 > 附加库目录：/A。添加SDK的lib目录路径（如 E:\aliyun-mq-windows-cpp-sdk\lib\64，包含相关的DLL文件）。若在Windows 7环境下使用Visual Studio 2015，还需额外添加ucrt库路径（如 C:\Program Files (x86)\Windows Kits\10\Lib\10.0.10150.0\ucrt\x64）。

    6. 右键单击项目，依次选择属性 > 配置属性 > 链接 > 输入 > 附加依赖项：ONSClient4CPP.lib。

    7. 右键单击项目，依次选择属性 > 配置属性 > C/C++-常规 > 预处理器定义：添加WIN32宏。

    Visual Studio非2015环境下使用C++ SDK

    1. 首先需要按照Visual Studio 2015的环境来配置，配置过程同Visual Studio 2015环境下使用C++ SDK。

    2. 安装vc_redist.x64。这是Visual C++ 2015的运行时环境。

      重要

      如果不想进行繁琐的设置，您也可以使用设置好的SDK Demo，下载SDK后进行解压，然后进入demo目录，使用Visual Studio 2015打开工程。

      在 Solution Explorer 中右键点击 demo 项目，打开属性页。将 Configuration 设为 Release，Platform 设为 x64。展开 Configuration Properties > C/C++ > General，编辑 Additional Include Directories 字段，添加两条路径：../../include 和 C:\Program Files (x86)\Windows Kits\10\Include\10.0.10150.0\ucrt。请将路径中的版本号（如 10.0.10150.0）替换为您机器上实际安装的 Windows Kits 版本号。

      到此为止就设置好编译环境了。单击Build，即可编译出可执行的程序，然后拷贝dll到可执行程序的目录下即可运行，或者拷贝dll到系统目录下。

    更多信息

    示例代码