使用Boost JSON解析响应时遭遇重复符号链接错误的技术求助

我正在开发一个基于Boost HTTP和WebSocket客户端的应用，需要解析服务器返回的JSON响应，因此采用boost/json库实现。项目包含HTTPClient和WebsocketClient两个类，这两个类被A、B等业务类引用，最终所有文件都被包含进main.cpp中。单个文件编译都能成功，但链接所有目标文件时出现大量重复符号错误，其中典型错误如下：

duplicate symbol '__ZN5boost4json6detail16default_resource11do_allocateEmm' in:
    /app/src/A.o
    /app/src/main.o
    /app/src/B.o
    /app/src/C.o
    /app/src/HTTPClient.o
    /app/src/WebsocketClient.o

我尝试将boost/json的头文件引用从.hpp移至.cpp文件，但仍出现340个重复符号错误。奇怪的是，项目中使用的其他Boost库（如Beast、SSL）并未出现此类问题，想了解boost/json库的特殊之处以及解决方法。

项目文件结构及代码如下：

HTTPClient.hpp #

#ifndef HTTPCLIENT_HPP
#define HTTPCLIENT_HPP
#include <boost/json.hpp>

class HTTPClient {
    public:
        HTTPClient(boost::json json_val);
};
#endif

HTTPClient.cpp #

#include <HTTPClient.hpp>
#include <boost/beast/ssl.hpp>

HTTPClient::HTTPClient(boost::json json_val) {
    // 使用boost::ssl的代码
}

WebsocketClient.hpp #

#ifndef WEBSOCKETCLIENT_HPP
#define WEBSOCKETCLIENT_HPP
#include <boost/json.hpp>

class WebsocketClient {
    public:
        WebsocketClient(boost::json json_val);
};
#endif

WebsocketClient.cpp #

#include <WebsocketClient.hpp>
#include <boost/beast/ssl.hpp>
#include <jwt-cpp/jwt.h>

WebsocketClient::WebsocketClient(boost::json json_val) {
    // 使用boost::ssl的代码
    // 使用jwt的代码
}

A.hpp #

#ifndef A_HPP
#define A_HPP
#include <WebsocketClient.hpp>

class A {
    public:
        A();
        void do_something();
    private:
        WebsocketClient ws;
};
#endif

B.hpp #

#ifndef B_HPP
#define B_HPP
#include <HTTPClient.hpp>

class B {
    public:
        B();
        void do_something_else();
    private:
        HTTPClient client;
};
#endif

Util.hpp #

#ifndef UTIL_HPP
#define UTIL_HPP

// 工具函数
class Util {
    public:
        Util();
        void foo();
};

#endif

Util.cpp #

#include <Util.hpp>

Util::Util() {
    
}

void Util::foo() {
    
}

main.cpp #

#include <A.hpp>
#include <B.hpp>
#include <Util.hpp>
int main() {
    A a;
    B b;

    a.do_something();
    b.do_something_else();

    Util u;
    u.foo();
}

Makefile #

CXX := g++

CXXFLAGS := -std=c++17 -O3 -Iinclude

INC_DIRS := -I/usr/local/include/boost_1_85_0/boost -I/usr/local/include/jwt-cpp 

LIB_DIRS := -L/opt/openssl@3/lib

LIBS := -lpthread -lcrypto -lssl

SRCS = main.cpp Util.cpp HTTPClient.cpp WebsocketClient.cpp A.cpp B.cpp
OBJS = $(SRCS:.cpp=.o)

TARGET = main

$(TARGET): $(OBJS)
    $(CXX) $(CXXFLAGS) $(LIB_DIRS) $(LIBS) -o $(TARGET) $(OBJS)

%.o: %.cpp
    $(CXX) $(CXXFLAGS) $(INC_DIRS) -c $< -o $@

clean:
    rm -f $(TARGET) $(OBJS)

.PHONY: clean

Boost.JSON库的设计和其他Boost库（如Beast）存在差异：

• 它并非完全的header-only库，部分内部实现（如detail命名空间下的资源分配类）会生成非inline符号，当多个编译单元都包含boost/json.hpp时，这些符号会被多次实例化，导致链接时重复定义错误。
• 若未显式链接Boost.JSON的预编译库，也未开启header-only模式，就会触发这类问题。

1. 链接Boost.JSON库 #

修改Makefile中的LIBS变量，添加-lboost_json（如果使用静态库，需根据Boost编译方式调整为-lboost_json-static）：

LIBS := -lpthread -lcrypto -lssl -lboost_json

2. 启用Header-Only模式 #

如果希望保持纯header-only使用，在编译选项中添加BOOST_JSON_HEADER_ONLY宏，强制Boost.JSON将所有实现转为inline，避免符号重复。修改Makefile的CXXFLAGS：

CXXFLAGS := -std=c++17 -O3 -Iinclude -DBOOST_JSON_HEADER_ONLY

3. 优化头文件引用 #

尽量避免在头文件中直接包含<boost/json.hpp>，将其移至.cpp文件中。如果头文件需要使用boost::json的类型，可以使用前向声明（复杂模板类型需注意完整参数定义，或改用指针/引用延迟实例化）。

例如修改HTTPClient.hpp：

#ifndef HTTPCLIENT_HPP
#define HTTPCLIENT_HPP

// 前向声明boost::json::value
namespace boost { namespace json { class value; } }

class HTTPClient {
    public:
        HTTPClient(const boost::json::value& json_val); // 使用引用避免拷贝
};
#endif

然后在HTTPClient.cpp中包含<boost/json.hpp>。

4. 验证Boost编译一致性 #

确保你的Boost库是用C17标准编译的，和项目的-std=c++17选项匹配。不同C版本编译的Boost库可能导致符号不兼容。

内容的提问来源于stack exchange，提问作者Isaac Martinez Jr. Mora