xmake构建工具实战：从安装到项目模板与依赖管理

还没写坑之前，先多说一句：这篇文章不是给大佬看的。大佬们多半已经用熟了CMake，或者正在Bazel/Meson里打滚。我这篇是写给那些和我一样，受够了Makefile的玄学、受够了CMake那套“看似入门实则劝退”的语法、又希望有一个现代构建工具能真正帮自己省时间的人。

我第一次接触xmake是两年前，在GitHub上刷到一个C++项目，没有CMakeLists.txt，只有一个叫xmake.lua的文件，当时第一反应是“又一个玩具”。后来项目里临时要拉一个跨平台的小工具，懒得再写CMake那一大坨，就试了试xmake create，结果从创建项目到编译出第一个可执行文件，前后不到两分钟。那一刻我意识到，这可能才是国产构建工具里最被低估的一个——它不声不响地把“从一个目录到一个能跑的项目”这件事做到了极致。

这篇文章我会从安装讲起，逐个拆解xmake创建项目模板的完整流程，包括模板参数、目录结构、编译配置、多目标拆分、第三方依赖集成，以及我在实际项目中踩过的几个坑。无论你是刚接触构建工具的新手，还是打算从CMake迁过来的老手，我相信这里面都有你能直接拿走用的东西。

1. 安装这件事，没那么玄乎但也不该掉链子

先说安装，毕竟工具都没装好，后面全是空谈。xmake的安装方式非常多，覆盖Windows、macOS、Linux三大平台。它的设计理念是“零依赖”，安装包本身不依赖Python、Ruby这类运行时，装完就是一个可直接执行的二进制，这点对我这种喜欢在干净环境里折腾的人非常友好。

1.1 Linux和macOS下的安装方式

在Linux和macOS下，我目前最推荐的是官方提供的curl安装脚本。官方脚本支持本地安装和全局安装两种模式：

bash复制# 全局安装（需要root权限，会安装到 /usr/local/xmake）
curl -fsSL https://xmake.io/get.sh | bash

# 本地安装（安装到当前用户目录 ~/.local/xmake，不需要root）
curl -fsSL https://xmake.io/get.sh | bash -s -- --local

官方安装脚本的逻辑很简单：检测系统架构和平台，下载对应版本的预编译二进制包，然后解压到指定目录，并自动配置环境变量。如果是本地安装，脚本结束后会提示你把 ~/.local/xmake 里的环境变量配置追加到shell配置文件里。

我个人的习惯是优先使用 --local 本地安装，理由有两个：一是很多开发机上我没有root权限，本地安装完全够用；二是本地安装不会污染系统目录，将来要卸载直接删目录就行，不用跟包管理器较劲。装完以后验证一下版本：

bash复制xmake --version

看到版本号输出就说明环境变量已经生效了，如果提示找不到命令，多半是shell配置没有source。手动source一下：

bash复制source ~/.bashrc   # 或者 source ~/.zshrc

1.2 Windows下的安装方式

Windows用户选择就更多了，我体验下来最舒服的还是用Scoop或winget：

bash复制# winget
winget install xmake

# Scoop
scoop install xmake

如果你两种包管理器都没装，也可以直接去GitHub Releases页面下载安装包，官方提供了.exe安装包和免安装的压缩包。安装包版可以自动配置环境变量，免安装版解压以后需要手动把xmake所在目录加到PATH里。

Windows上有一个比较特殊的点：xmake默认会尝试自动检测Visual Studio的编译环境，然后用MSVC作为默认工具链。如果你机器上装了VS但是xmake没识别到，可以显式指定一下：

bash复制xmake f --toolchain=msvc

如果你习惯用MinGW，也可以强制切到gcc工具链：

bash复制xmake f --toolchain=mingw

这里插一句，xmake的编译配置信息是在你执行 xmake f（全称 xmake f --rebuild 之前的那次 xmake f，即 xmake config）时写入缓存并保存的，后续再次编译会沿用上次配置。所以改了工具链之后，最稳妥的方式是加 --rebuild 参数强制全量重建，避免缓存中的旧配置干扰新配置。

1.3 源码编译安装属于进阶玩法

如果你用的Linux发行版太老，官方预编译包可能不兼容，或者你就是想体验一把“从源码构建构建工具”的快乐，也可以源码编译安装。xmake本身是用C语言写的，编译它需要一个C编译器（gcc或clang都行），步骤很简单：

bash复制git clone --depth=1 https://github.com/xmake-io/xmake.git
cd xmake
make
./scripts/get.sh --local

源码编译的好处是你总能拿到最新开发版的特性，坏处是偶尔会遇到某些分支版本不太稳定。我建议普通用户就老老实实用官方安装脚本，没必要在生产环境上给自己找麻烦。

2. 创建项目模板：一次xmake create背后的完整逻辑

安装搞定，接下来进入正题。xmake create 是xmake创建项目模板的核心命令，它做的事情远不止“在当前目录生成几个文件”那么简单，里面涵盖了模板引擎、项目类型识别、编译方式预设、目标平台配置等一系列逻辑。理解这层机制，你才能真正用好它。

2.1 最简单的创建方式

我最常用的创建命令是：

bash复制xmake create hello

这条命令会在当前目录下创建一个名为hello的子目录，并生成一个最小的C++可执行文件项目。目录结构如下：

bash复制hello/
├── src/
│   └── main.cpp
└── xmake.lua

xmake.lua 就是xmake项目的灵魂配置文件，内容大概长这样：

lua复制add_rules("mode.debug", "mode.release")

target("hello")
    set_kind("binary")
    add_files("src/*.cpp")

就这么几行，一个完整可编译的项目就成型了。和CMake比起来，你会觉得这更像是“配置”而不是“编程”——没有到处可见的${CMAKE_SOURCE_DIR}宏，没有include_directories和link_directories之间的来回拉扯，更不需要为了一个简单的hello world写出三四十行配置。

这也是xmake最核心的设计哲学：绝大多数场景下，你应该写的只是“项目里有哪些目标、每个目标包含哪些源文件”，而不是去描述“怎么编译、怎么链接”。 底层那些复杂的编译命令、头文件搜索路径、库搜索路径，xmake会自动推断。

2.2 语言与目标类型的选择

xmake create 默认生成的模板语言是C++，但它的模板系统其实覆盖了C、C++、Objective-C、Swift、Go、Rust、D语言、Java等多种语言。指定语言用 -l 参数：

bash复制xmake create -l c hello_c
xmake create -l go hello_go
xmake create -l rust hello_rust

-l 是 --language 的简写，如果你需要查看当前支持的完整语言列表，可以直接执行：

bash复制xmake create --help

顺便说一个我自己经常使用的技巧：如果你只是想快速创建一个项目，又没想好到底用什么语言，可以先不指定 -l，直接xmake create demo，默认会用C++。等后面改了主意，再把源代码文件替换掉、把xmake.lua里的配置微调一下就行，成本很低。

除了语言维度，还可以用 -t 参数指定项目模板类型，-t 是 --template 的简写：

bash复制# 创建一个静态库项目
xmake create -t static hello_static

# 创建一个共享库项目
xmake create -t shared hello_shared

# 创建一个Qt应用程序项目
xmake create -t qt hello_qt

# 创建一个控制台程序项目（默认就是这种）
xmake create -t console hello_console

-t 参数决定了生成的目标类型（set_kind 的值）以及配套的源代码骨架。比如创建静态库项目时，xmake.lua 里的 set_kind 会是 "static"，而控制台程序则是 "binary"。搞清楚这个对应关系后，你以后看到一个项目目录就知道这大概是个什么形态的目标了。

2.3 创建到指定目录和强制覆盖

默认情况下，xmake create hello 会在当前目录下新建hello目录；如果你希望项目直接创建在当前目录（比如在当前已存在的空目录里初始化项目），可以用 -P 参数（--project的简写）：

bash复制xmake create -P .

如果你在已有项目的目录下误执行了创建命令，会提示目录已存在或文件冲突。这时候可以加 -f 强制覆盖：

bash复制xmake create -f -P . hello

这个-f参数我平时用得不多，因为强制覆盖容易把已有文件冲掉，所以每次用之前我都会确认一下目录里的文件是否有备份。宁可多花十秒看一眼，也别让构建工具帮自己做了“删库跑路”的操作。

2.4 模板到底从哪里来

xmake的模板不是写死在代码里的，它内部有一套基于Lua的模板引擎机制。系统内置模板存放在xmake安装目录下的 templates 文件夹中，每种模板由以下两部分组成：

• 模板目录：包含项目文件骨架（如src/main.cpp、xmake.lua）
• 模板定义：描述这个模板的说明信息、参数规则、生成逻辑

如果你有定制模板的需求，可以将自己的模板放到 ~/.xmake/templates 目录下，然后在创建时通过 -t 模板名 直接引用。比如团队内部有一套统一的代码规范、统一的目录结构和统一的编译选项，就可以把这一整套沉淀为一个xmake模板，以后新成员入职，一行命令就能拉起符合规范的新项目。

这个机制我后文会展开讲，这里你先记住一个结论：xmake create 本质上是在“渲染一份模板”，并不是简单地复制文件。

3. 手写xmake.lua基础配置：小模板背后的大文章

上一步创建出来的模板只是个起点。一个项目从“能跑”到“好用”，中间有大量的配置细节需要自己写。这一节我把xmake.lua里最核心的配置逐行拆开来讲，顺便解释一下每个配置背后的逻辑。因为xmake的语法是Lua，很多习惯写CMake的人会问“要不要学Lua”，实际上你只需要会用 target()、set_kind()、add_files() 这几个基础API就够了，根本不需要完整学一遍Lua语言。

3.1 目标(target)是xmake配置的核心单位

xmake里最核心的概念是target。一个target对应一个编译产物，可以是可执行文件（binary）、静态库（static）、共享库（shared）甚至是一些更特殊的类型。

lua复制target("hello")          -- 定义一个名为hello的目标
    set_kind("binary")    -- 指定目标类型为可执行程序
    add_files("src/*.cpp") -- 添加源文件
end

看到没有，这就是xmake最吸引我的地方——target的定义和语义化配置是一体的。在CMake里，不同目标的配置通常散落在add_executable、target_include_directories、target_link_libraries等多个命令中，而xmake把同一目标的所有配置都收拢在了一个代码块里。我后来迁移老项目时有一个直观感受：同样一个项目，CMake配置我需要上下翻屏才能看清某个target的全貌，xmake只需要看这个target块就够了。

一个xmake.lua里可以定义多个target：

lua复制target("core")
    set_kind("static")
    add_files("src/core/*.cpp")
end

target("app")
    set_kind("binary")
    add_files("src/app/*.cpp")
    add_deps("core")   -- 依赖core目标
end

这种写法的好处是依赖关系一目了然。后面编译时，xmake会自动处理target之间的构建顺序，你不用手动关心先编core还是先编app，它会按照依赖图自动安排。

3.2 常用配置项逐个拆解

我把平时代码里最常用到的一组配置整理成了下面的表格，方便查阅：

这里面有几个我理解了很久才彻底搞明白的细节：

add_links 和 add_linkdirs 需要配合使用吗？答案是看情况。如果库文件在系统默认的搜索路径里（比如/usr/lib），只要写 add_links("z") 就够了；如果库文件放在项目自定义目录（比如lib/下），那就两个都要写：

lua复制target("demo")
    set_kind("binary")
    add_files("src/*.cpp")
    add_linkdirs("lib")
    add_links("foo")
end

也不一定需要把 lib/libfoo.so 写全，xmake会自动根据目标平台去查找libfoo.so（Windows上则是foo.lib）。这比CMake的find_library要省心太多，我在CMake里经常为了找一个非系统目录下的库写一堆set(CMAKE_FIND_LIBRARY_SUFFIXES)之类的操作，到xmake这里一行就解决了。

set_languages 这个配置也很值得说。很多新手刚上手时直接写 add_cxxflags("-std=c++17")，结果发现在Windows上用MSVC编译时报错。原因是MSVC不认识-std=c++17这种GCC风格的参数，它需要的是/std:c++17。xmake的 set_languages("c++17") 会帮你做这层适配，在GCC/Clang下生成-std=c++17，在MSVC下自动转换成对应的/std:c++17。

lua复制set_languages("c++17")

这是xmake“跨平台一致性”设计的具体体现之一。用 add_cxxflags 这种底层接口虽然直白但容易踩平台差异的坑，优先使用语义化配置接口是更稳妥的选择。

3.3 不同编译模式的切换

xmake内置了两个很常用的规则：mode.debug 和 mode.release。在模板生成时，这两行规则默认就写在xmake.lua里：

lua复制add_rules("mode.debug", "mode.release")

这两行规则的实际作用是：当你执行 xmake f -m debug 时，xmake会自动加上带调试信息的编译参数（比如-g、-O0）；当你执行 xmake f -m release 时，它会自动加上优化参数（比如-O3、-DNDEBUG）。默认的构建模式是release，如果你想调试，需要先切换配置，再重新编译：

bash复制xmake f -m debug
xmake -r

这里-r是--rebuild的简写，表示强制全量重编译。我在实际调试时经常遇到一种情况：断点打不上、变量看不出来，最后发现是因为没切到debug模式，编译产物还是release版。这种问题排查起来特别浪费时间，所以我现在养成一个习惯：新项目创建完，第一次配环境时就先切换到debug模式编译一次，确认调试信息正常后再干别的事。

3.4 平台条件判断

xmake的配置是Lua语法，天然支持条件判断。在CMake里，平台判断通常要写 if(WIN32)、elseif(APPLE) 之类的分支；在xmake里更直接，直接判断 is_plat：

lua复制if is_plat("windows") then
    add_defines("WIN32_LEAN_AND_MEAN")
    add_links("ws2_32")
elseif is_plat("linux") then
    add_links("pthread")
end

这种写法的可读性比CMake高不少，因为它就是普通编程语言的if/else结构，不需要额外记一套构建系统自己的逻辑表达式语法。

4. 从单文件到多文件：项目模板的第一次“长个儿”

前面讲的都是模板创建和基础配置，实际写代码时，几乎没有人会一直停留在单文件状态。这一节我们拿一个真实场景来演示：从一个最简单的hello模板开始，逐步扩展成一个包含多个模块、多个目标类型的项目。这个过程会涉及到目录结构调整、多文件递归添加、静态库抽取、共享库链接等操作。

4.1 场景设定

假设我们要实现一个简单的计算器程序，支持加减乘除四则运算。功能虽然简单，但我希望项目结构能体现出软件工程的基本分层思想：

bash复制calculator/
├── include/
│   └── calculator/
│       └── calc.h
├── src/
│   ├── core/
│   │   └── calc.cpp
│   └── main.cpp
└── xmake.lua

• calc.h 声明计算器接口
• calc.cpp 实现具体运算逻辑
• main.cpp 作为程序入口调用计算器接口

这样一个结构的好处是：计算核心（core）可以被复用，将来如果需要做单元测试，可以直接将src/core和include/calculator打包成一个测试目标，不需要额外调整代码。

4.2 第一步：创建基础项目

先用xmake创建骨架：

bash复制xmake create -P calculator
cd calculator

-P 参数确保项目直接创建在calculator目录内。此时xmake.lua和src/main.cpp已经生成，接下来我们手动调整目录结构。

4.3 第二步：编写头文件和核心实现

先看include/calculator/calc.h：

cpp复制#pragma once

namespace calculator {

int add(int a, int b);
int subtract(int a, int b);
int multiply(int a, int b);
int divide(int a, int b);

}

再看src/core/calc.cpp：

cpp复制#include "calculator/calc.h"

namespace calculator {

int add(int a, int b) {
    return a + b;
}

int subtract(int a, int b) {
    return a - b;
}

int multiply(int a, int b) {
    return a * b;
}

int divide(int a, int b) {
    if (b == 0) {
        return 0;
    }
    return a / b;
}

}

最后看src/main.cpp：

cpp复制#include <cstdio>
#include "calculator/calc.h"

int main() {
    int a = 20;
    int b = 4;
    std::printf("%d + %d = %d\n", a, b, calculator::add(a, b));
    std::printf("%d - %d = %d\n", a, b, calculator::subtract(a, b));
    std::printf("%d * %d = %d\n", a, b, calculator::multiply(a, b));
    std::printf("%d / %d = %d\n", a, b, calculator::divide(a, b));
    return 0;
}

代码本身很简单，但请注意头文件的包含路径是"calculator/calc.h"而不是"calc.h"，我特意用了带子目录的写法，目的是让整个项目的头文件组织方式从一开始就保持可扩展性。如果将来头文件数量多了，可以按模块继续分子目录，不会乱套。

4.4 第三步：重写xmake.lua

现在重点来了，我们要按项目结构重新配置xmake.lua：

lua复制add_rules("mode.debug", "mode.release")

target("calc_core")
    set_kind("static")
    add_files("src/core/*.cpp")
    add_includedirs("include", {public = true})
end

target("calculator")
    set_kind("binary")
    add_files("src/*.cpp")
    add_deps("calc_core")
    add_includedirs("include", {public = true})
    set_languages("c++17")
end

这里有几个关键点需要展开说：

第一，add_files("src/core/*.cpp") 默认只匹配core目录下的直接文件，如果你把src/core下面再细分了子目录，则需要用递归匹配写法 add_files("src/core/**.cpp")。 ** 表示递归任意层级。这个通配符的坑我刚开始用时就踩过，以为自己写了个*.cpp就能覆盖所有子目录，结果.cpp文件在二级子目录里根本不会被编译，链接时一堆找不到符号的错误。后来我把所有add_files都养成了一个习惯：不确定目录深度时，就直接用**.cpp。

第二，add_includedirs("include", {public = true}) 中的{public = true}是xmake中非常实用但经常被忽略的配置。 它的作用是把这个头文件搜索路径同时传递给依赖这个target的其他target。也就是说，calculator 通过 add_deps("calc_core") 依赖了calc_core，同时自动继承了calc_core里public标记的头文件搜索路径，所以calculator里的源码就能直接#include "calculator/calc.h"，无需重复添加add_includedirs("include")。

这个设计思路和CMake里target_include_directories(... PUBLIC ...)的语义是一样的，但xmake的写法更直观一些。如果去掉{public = true}，你很快就会遇到“单独编译calc_core没问题，一旦主程序include了calc_core的头文件就报找不到”的诡异问题。我在刚把CMake项目迁到xmake时，这里就绕了不小的弯子。

第三，add_deps("calc_core") 建立依赖关系后，xmake会保证先编译静态库calc_core，再编译可执行文件calculator，并自动将静态库链接进来。 你并不需要额外写add_links("calc_core")。这一点和CMake不同，在CMake里，target_link_libraries 既负责链接库，又负责传递头文件路径和编译选项；在xmake里，这层依赖和传递关系由 add_deps + {public = true} 两个机制共同完成。

4.5 第四步：编译运行

配置写完，直接编译：

bash复制xmake

正常的话，你会看到类似下面的输出：

bash复制[  0%]: ccache compiling.release src/core/calc.cpp
[ 50%]: ccache compiling.release src/main.cpp
[100%]: linking.release calculator

然后运行：

bash复制xmake run

输出：

bash复制20 + 4 = 24
20 - 4 = 16
20 * 4 = 80
20 / 4 = 5

整个过程从创建项目到跑出结果，不超过两分钟。如果这个项目将来要继续长大，比如想给“计算器的核心逻辑”单独写单元测试，你只需要再定义一个target，把src/core/calc.cpp和测试文件一起编译就行了，calc_core的calc.cpp并不会被重复编译进主程序，依赖关系是清晰的。

5. 一条命令搞定第三方依赖：xmake的内置包管理系统

模板项目和第一个规模化项目都搞定之后，真正让xmake拉开与其他构建工具差距的，是它内置的包管理能力。你不需要额外装vcpkg或conan，xmake本身就集成了一个远程依赖获取机制，一行add_requires就能引入第三方库。

5.1 从零引入一个库

还是用刚才的计算器项目举例，假设我想让程序支持读取用户输入的表达式并求值，比如输入"3 + 5 * 2"，程序自动给出结果。自己手写表达式解析器也不是不行，但完全没有必要重复造轮子，这里引入一个成熟的C++表达式求值库exprtk。

修改xmake.lua，加入：

lua复制add_requires("exprtk", {configs = {enable_debug = false}})

target("calculator")
    set_kind("binary")
    add_files("src/*.cpp")
    add_deps("calc_core")
    add_includedirs("include", {public = true})
    add_packages("exprtk")
    set_languages("c++17")
end

第一行 add_requires 声明了项目需要exprtk这个依赖包；target内部的 add_packages("exprtk") 表示这个目标会使用该包。这两者必须同时出现，否则xmake不知道该把这个包应用到哪个目标上。

重新编译：

bash复制xmake

如果本地没有缓存，xmake会先在线下载exprtk源码并编译安装到它的本地包缓存目录中，然后再编译你的项目。这个过程完全自动，不需要你手动去配置库路径。

5.2 版本约束和平台差异

add_requires 支持版本约束，用语义化版本号：

lua复制add_requires("fmt >= 8.0.0", "spdlog >= 1.10.0")
add_requires("zlib 1.2.x")

还支持平台差异：

lua复制if is_plat("windows") then
    add_requires("winhttp")
else
    add_requires("libcurl")
end

这种“按需取包、平台自适应”的体验，在我看来已经接近现代语言包管理器（比如npm、cargo）的水准了。而CMake的FetchContent在下载依赖时还要手动处理很多细节，vcpkg虽然也在进化，但和xmake这种原生集成的顺畅度相比还是稍逊一筹。

5.3 包缓存跟编译产物的关系

有一个细节需要单独提醒。xmake在引入远程包后，首次编译会在本地建立一个包缓存目录，后续重新编译项目时一般会直接复用缓存包，不会每次都重新下载。如果你改了包的版本号并重新配置，可能会遇到旧的缓存包还占着目录的情况。此时可以清理缓存：

bash复制xmake f -c

-c是--clean的简写，表示清理配置缓存。加上-c会强制xmake重新评估所有配置并重新拉取依赖包，能解决不少诡异问题。这个命令我用得非常频繁，基本成了“遇到奇怪问题先洗一遍配置”的肌肉记忆。

6. 模板自定义：把团队的项目骨架一键化

前面讲的是如何使用xmake自带的模板。但一个工具真正好用的地方，往往在于你能按照自己的习惯改造它。xmake支持自定义项目模板，这一节我会以“团队内部C++服务项目模板”为例，完整演示如何创建一个自定义模板，让新项目初始化时自动生成指定的目录结构、代码风格和基础配置。

6.1 模板目录结构

xmake的自定义模板放在~/.xmake/templates目录下，每个模板一个子目录。模板目录的规范结构是：

bash复制~/.xmake/templates/
└── my-service/              # 模板名称为 my-service
    ├── xmake.lua            # 模板定义文件（注意，不是项目的构建文件）
    └── template/
        ├── xmake.lua        # 项目模板中的构建配置
        ├── .gitignore       # 项目模板中的gitignore
        └── src/
            ├── main.cpp
            └── version.h.in

template目录下存放的才是真正会复制到新项目里的文件。需要注意的区分是：

• 模板根目录下的xmake.lua是模板定义脚本，负责描述模板的逻辑，比如按用户输入生成特定文件名、修改变量等
• template/目录下的xmake.lua是项目构建脚本，它会被原样复制到新项目中，成为新项目的xmake.lua

这个区分很容易混淆，我第一次搞的时候就把两个xmake.lua写岔了，结果模板创建出来以后项目配置完全不对。

6.2 模板定义脚本

来看~/.xmake/templates/my-service/xmake.lua：

lua复制-- 模板描述信息
description("my-service template")

-- 模板创建时动态渲染
function main()
    -- 从系统时间生成版本号
    local year = os.date("%Y")
    local version = "1.0.0"

    -- 将模板文件复制到目标目录
    local template_dir = path.join(os.scriptdir(), "template")
    os.cp(path.join(template_dir, "*"), projectdir)

    -- 替换版本号占位符
    local version_file = path.join(projectdir, "src/version.h.in")
    local content = io.readfile(version_file)
    content = content:gsub("${VERSION}", version)
    content = content:gsub("${YEAR}", year)
    io.writefile(path.join(projectdir, "src/version.h"), content)
    os.rm(version_file)

    -- 输出提示
    cprint("${bright green}my-service template generated!${clear}")
end

这段脚本的逻辑是：先将template目录下的所有文件复制到用户执行xmake create时的目标项目目录（projectdir指向的就是新项目目录），然后读取version.h.in模板文件，进行版本号和年份的占位符替换，最后删除version.h.in并保留最终生成的version.h。

6.3 项目构建脚本模板

再看template/xmake.lua（这是将来每个新项目都会有的构建脚本）：

lua复制add_rules("mode.debug", "mode.release")

set_version("1.0.0")

target("${PROJECT_NAME}")
    set_kind("binary")
    add_files("src/*.cpp")
    add_includedirs("include", {public = true})
    set_languages("c++17")
end

${PROJECT_NAME} 是占位符，你可以在模板定义脚本中把它替换成用户创建项目时传入的项目名。比如：

lua复制local project_name = os.projectname()
content = content:gsub("${PROJECT_NAME}", project_name)

os.projectname() 对应的就是执行 xmake create -P myservice 时传入的项目名。

6.4 使用自定义模板

模板创建好以后，使用方式和系统模板完全一致：

bash复制xmake create -t my-service -P myservice

执行后，myservice目录下会自动出现完整的项目骨架、版本头文件和构建配置。团队里新同学入职，只需要知道这一个命令就能拉起来和团队规范完全一致的新项目。

我现在的团队就是这么干的。我们把公司内部的日志库、网络库、公共工具库的依赖都写在了模板的xmake.lua里，新项目初始化时几条add_requires就自动带上了，大家再也不用去公司内部Wiki里翻“新项目初始化步骤”那篇永远没人更新维护的文档。

7. 常见坑和排查思路：我在这条路上踩过的几个真坑

任何工具用久了都会踩坑，xmake虽然设计得很顺手，但也不是没有“坑”。这一节分享几个我实际遇到过的、有一定代表性的问题以及排查思路。

7.1 “配置正确但编译不过”的头文件路径传递问题

现象：calc_core目标单独编译完全没问题，但calculator目标编译时会报“找不到 calculator/calc.h”。

排查思路：这类问题几乎可以断定是头文件搜索路径没有被正确传递给依赖方。检查add_includedirs是否添加了{public = true}属性。没有public标记的add_includedirs只在当前target内生效，依赖它的target拿不到这个路径。加上{public = true}后再重新执行：

bash复制xmake f -c && xmake

这个问题在xmake的issue区反复出现过，很多从CMake转过来的人都踩过。CMake里target_include_directories默认就是PUBLIC（如果你不写访问级别，在不同版本下有差异），所以习惯性地以为xmake也会自动传递头文件路径，结果就踩坑了。

7.2 “循环依赖”和构建顺序错乱

现象：target A依赖target B，target B也依赖target A，编译时报循环依赖错误。

排查思路：这是工程层面的设计问题，不是xmake的bug。检查target之间的依赖关系，确认是否存在循环。如果是由于符号互相引用导致的依赖，建议把公共代码抽到第三个target中，形成更清晰的依赖层次。比如A和B都依赖C，而不是A依赖B、B依赖A。

7.3 包下载失败或版本不匹配

现象：add_requires("foo") 后执行xmake，一直卡在下载阶段，或者下载完成后编译报错，提示找不到头文件。

排查思路：

先看网络是否正常。xmake默认从GitHub等源拉取包，在某些网络环境下可能不太稳定。可以检查本地缓存目录（~/.xmake/cache）有没有残留文件；如果有，删掉后重新xmake f -c && xmake。

再看版本约束是否过于严格。比如add_requires("foo 1.2.x")可能拉到最后一个小版本，如果这个版本恰好有编译兼容性问题，就会报错。可以放宽到add_requires("foo >= 1.2.0, < 2.0.0")，或者干脆尝试指定一个已知稳定的版本。

如果仍然拉不下来，还可以检查是不是代理设置的问题。我在内网开发机上遇到过因为公司代理导致GitHub源不可用的情况，设置代理后就好了。

7.4 MSVC和GCC下行为不一致

现象：同一份代码在Linux下用GCC编译没有任何问题，切到Windows上用MSVC编译就开始报错，警告也多了一堆。

排查思路：这不能全怪xmake，跨平台编译本来就容易遭遇到编译器的差异问题。但xmake的一些配置写法确实会影响一致性。我的建议是：

• 优先使用set_languages声明语言标准，而不是直接add_cxxflags
• 平台差异逻辑用is_plat分支显式处理，不要想当然认为所有平台都支持同一个编译选项
• 用add_defines统一宏定义，避免在代码里写#ifdef _WIN32之外还要额外加编译参数

xmake的跨平台能力很强，但跨平台不是“写了配置文件就自动跨”，而是“配置的抽象层帮你把大多数差异隔离掉了”。编译器的个性差异仍需要开发者自己处理。

7.5 重新编译了但运行的不是新代码

现象：修改了代码，执行xmake，显示updating...然后编译，但运行起来行为没有任何变化。

排查思路：大概率是编译模式和上次不一致。比如上次是release模式，改代码后执行xmake f -m debug切到了debug模式，如果不加-r强制重建，链接器可能没有把修改过的源文件重新链接进去。此时执行：

bash复制xmake f -m debug -c && xmake -r

先清理配置缓存，再全量重建。这条命令基本能解决90%的“改了代码没生效”类问题。另外一个可能的原因是add_files路径没有匹配到新增的源文件，如果新增了子目录下的.cpp，记得检查是否用了**.cpp递归匹配。

8. 从CMake迁移到xmake的心理建设和操作路径

关于迁移这个话题，我在自己的一个老项目上完整实践过。那是一个积累了三年多的C++项目，用CMake写了上千行配置，n多个target，还有一堆if分支处理平台差异。迁到xmake之后，配置从上千行缩减到两百多行，编译速度也有提升。

先泼一盆冷水：不要试图一次性把整个项目连根拔起全量迁移。 我把这种迁移节奏称为“从边缘试探”，先挑一个不重要的、不是核心链路的子模块单拉出来，用xmake单独编译，验证依赖关系、可执行性，跑通了再去动核心部分。

迁移的具体颗粒度，我习惯分三层：

• 库目标：先迁移make依赖的库，保持源文件路径不变，只改构建脚本
• 可执行目标：库目标迁移完成后，再迁移最终的可执行文件
• 测试和工具目标：最后考虑

迁移时最痛苦的部分通常是各种target_include_directories和target_link_libraries的映射关系。我的做法是先在CMake配置里梳理出每个target的include路径、依赖库和编译选项，然后像填表一样把这组信息映射到xmake的语义化配置上。

不建议用什么自动转换工具，因为两边语法差异太大，自动转换出来的配置往往是“能编译但可读性极差”，后面维护反而更难。手工迁移虽然慢，但迁移的过程本身就是对项目依赖关系的一次全面梳理，是个难得的内部体检机会。

9. 一个真实感想

聊了这么多，最后说点工具之外的东西。xmake这种构建工具在国内一直处于“叫好不叫座”的状态，很多程序员知道它、欣赏它，但真正投入产出、迁移老项目的还是少数。我觉得核心原因不是技术问题，而是“沉没成本”太高——CMake已经是事实标准，大家的经验、CI模板、IDE集成、队友的熟悉程度都堆在了CMake上，即便知道xmake更好用，也不容易说服团队为了“好用”去承担一次迁移成本。

但反过来看，对于新项目、新团队，xmake一定是值得优先考虑的选项。它把“创建项目”这件事的摩擦降低到了一个非常低的水平，内置包管理，跨平台体验好，模板机制能帮团队统一规范。就算你要用CMake，也建议先花两个晚上玩玩xmake，理解一下“配置”和“编程”之间应该有的边界。

如果在看这篇文章的你正准备搭一个新项目，我的建议是：直接跑一遍xmake create，亲手感受一下从零到能跑得多快。大概率你会回来把这篇收藏里的代码抄走的。