Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

使用 Sanitizer

什么是 Sanitizer?

Sanitizer 是一种静态检测工具,能够帮助找出传统调试器通常无法捕捉的问题。非常适合在持续集成中与 单元测试 结合使用。

在 Windows、macOS、Linux 平台使用 Clang(LLVM)、GCC、Visual Studio 编译器时能够使用 Sanitizer。部分平台可能也可以使用其独有的 Sanitizer。多种不同的编译器都提供相同的某种 Sanitizer 时,请记住它们的输出和行为有可能略有不同。

在 Godot 中使用 Sanitizer

Sanitizer 要求重新编译二进制文件。这意味着你无法使用官方 Godot 二进制文件来运行 Sanitizer。

When compiling with any of the sanitizers enabled, the resulting binary will have the .san suffix added to its name to distinguish it from a binary without sanitizers.

There is a performance impact as many additional runtime checks need to be performed. Memory utilization will also increase. It is possible to enable certain combinations of multiple sanitizers in a single build. Beware of the performance impact when using multiple sanitizers at once though, as the resulting binary may be excessively slow.

Certain options can be passed to sanitizers without having to recompile the binary using environment variables.

地址 Sanitizer(ASAN)

  • Clang 和 GCC 中可用。

  • 支持的平台:Linux、macOS、Windows(Visual Studio)、Web

  • Clang ASAN 文档

The address sanitizer is generally the most frequently used sanitizer. It can diagnose issues such as buffer overruns and out-of-bounds access. If the engine crashes with a message such as free(): invalid pointer, this is typically the result of a buffer overrun. (This message is printed by the C runtime, not Godot.)

In certain situations (such as detecting uninitialized memory reads), the address sanitizer doesn't suffice. The 内存 Sanitizer(MSAN) should be used instead.

It is also possible to detect use-after-return situations by specifying the ASAN_OPTIONS=detect_stack_use_after_return=1 environment variable before running Godot (not when compiling it). This increases the address sanitizer's runtime overhead, so only enable this feature when you actually need it.

To enable the address sanitizer in a Godot build, pass the use_asan=yes SCons option when compiling. Enabling ASAN generally makes the resulting binary about 2× slower.


Due to a design decision, the address, memory and thread sanitizers are mutually exclusive. This means you can only use one of those sanitizers in a given binary.

泄漏 Sanitizer(LSAN)

The leak sanit