如何正确实现C++单例模式？链接错误原因排查

问题描述 #

实现C++单例模式的Metadata类时，出现如下链接错误：

projectgen.cpp:(.bss+0x0): multiple definition of `Metadata::metadata'; C:\Users\adria\AppData\Local\Temp\ccdq4ZjN.o:main.cpp:(.bss+0x0): first defined here
collect2.exe: error: ld returned 1 exit status

相关代码 #

Metadata.h（单例类）

#pragma once
class Metadata
{
public:

    Metadata(Metadata &other) = delete;
    void operator=(const Metadata &other) = delete;

    static Metadata *getInstance()
    {
        return metadata;
    }

    static void createInstance(Ctor &params)
    {
        if (!metadata)
        {
            metadata = new Metadata(params);
        }
    }
protected:
    Metadata(Ctor &params)
    {
        m_vars = params;
    }

    static Metadata *metadata;

private:
    Ctor m_vars;
}; // 原代码遗漏分号，会导致编译错误

Metadata* Metadata::metadata = nullptr;

main.cpp

#include "metadata.h"

int main(void)
{
    Ctor ctor;
    Metadata::createInstance(ctor);
    Metadata* data = Metadata::getInstance();
    return 0;
}

projectgen.cpp

#include "metadata.h"

void ProjectGenerator::test()
{
    Metadata* data = Metadata::getInstance();
}

错误原因 #

这个链接错误的核心问题是：静态成员变量Metadata::metadata被定义在了头文件中。

C++中，当多个源文件（比如main.cpp和projectgen.cpp）都包含Metadata.h时，每个源文件都会生成一份Metadata::metadata的定义副本。链接器在合并所有目标文件时，发现同一个变量存在多个定义，就会抛出"multiple definition"错误。

注意#pragma once只能防止头文件在同一个源文件中被重复包含，无法阻止不同源文件分别包含头文件后生成多份变量定义。

修复方案 #

要解决这个问题，必须将静态成员变量的声明和定义分离：

1. 在Metadata.h中只保留静态成员变量的声明（即static Metadata *metadata;），删除头文件中的定义语句Metadata* Metadata::metadata = nullptr;。
2. 创建一个单独的源文件（例如Metadata.cpp），在其中添加静态成员变量的定义：

#include "Metadata.h"

// 静态成员变量的定义放在源文件中，确保仅定义一次
Metadata* Metadata::metadata = nullptr;

这样无论多少个源文件包含Metadata.h，静态变量只会在Metadata.cpp中被定义一次，链接器就不会再报重复定义的错误。另外别忘了补上原Metadata.h中类定义末尾遗漏的分号。

内容的提问来源于stack exchange，提问作者Adrian H.