TscanCode：超详细部署与使用教程

TscanCode 是腾讯开源的快速、精准静态代码分析工具，支持 C/C++、C#、Lua：单命令即可扫描代码缺陷，性能约 20 万行/分钟、准确率约 90%，无需严格编译环境，并且可扩展自定义检查规则。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

TscanCode 致力于帮助程序员在编码最早期发现代码缺陷。它脱胎于腾讯内部代码扫描实践，2017 年对外开源，定位是「快、准、易上手、可扩展」的轻量静态分析工具。

1.2 核心功能

• 多语言支持：C/C++、C#、Lua。
• 快速准确：性能可达 20 万行/分钟，准确率约 90%。
• 易使用：不要求严格编译环境，单条命令即可扫描；输出 XML 报告。
• 可扩展：可以基于 TscanCode 实现自己的检查规则（checker）。
• GUI 规则定制：v2.14.24 起 GUI 上线「规则包（Rule Package）」，规则定制更方便；GUI 支持标记误报（false-positive）。
• Lua 持续增强：v2.15.01 支持 Lua 5.4；v2.15.02 修复 Lua crash 并新增更多检查器。

1.3 技术架构

官方未提供公开可用的架构图/logo 图，以官方文档描述为准。 说明：仓库 README 中仅包含交流群二维码，无架构图；已尝试来源包括 GitHub 仓库 README、仓库目录结构、Releases 页面，均未发现可公开引用的项目图。

TscanCode 由命令行扫描器（CLI）与 GUI 两部分组成，核心检查引擎用 C++ 编写，内置丰富的检查规则（空指针、数组越界、资源泄漏、未初始化变量等），输出 XML 格式的错误清单。

典型可检出的缺陷类型（官方 README 示例与内置规则方向）：

• 空指针解引用（对 NULL 判断后的分支外解引用）；
• 数组越界访问；
• 文件句柄/内存未释放；
• 未初始化变量的使用；
• 算术/逻辑错误（除零、符号混淆）；
• Lua 脚本运行时崩溃风险（v2.15.02 增强）。

二、环境要求

三、部署方式

3.1 方式一：Linux 源码编译（推荐）

git clone https://github.com/Tencent/TscanCode.git
cd TscanCode
make

编译完成后在 trunk 目录下生成 tscancode 可执行文件（具体路径以编译输出为准）。编译过程中会用到仓库内置的 tinyxml（zlib 协议），无需额外安装依赖。

验证可执行文件：

chmod +x trunk/tscancode   # 路径以实际编译输出为准
./trunk/tscancode --help

3.2 方式二：Windows Visual Studio 编译

1. 用 Visual Studio 2015+ 打开 tscancode.sln；
2. 解决方案配置为 Release，平台选 x64 或 Win32；
3. 生成解决方案，得到扫描器与 GUI 程序。

解决方案默认配置面向 VS 2015，但平台工具集可方便切换到更新版本；解决方案同时包含 x86 与 x64 目标。

3.3 方式三：macOS 编译

git clone https://github.com/Tencent/TscanCode.git
cd TscanCode
make    # 系统自带 clang++

仓库还提供 tscancode.xcodeproj，可用 Xcode 打开编译。

说明：官方未提供预编译 release 包（releases 页面为空），所有平台均需从源码编译。

3.4 验证部署成功

# 对示例文件扫描
./tscancode --xml your_code.cpp 2>result.xml
cat result.xml

能正常输出 XML 报告即说明部署成功。

四、使用方法

4.1 基础用法

示例代码（潜在空指针缺陷）：

// func.cpp
void func(int* p) {
    if(p == NULL) {
        printf("p is null!");
    }

    printf("p is %d", *p);   // p 可能为空，解引用不安全
}

执行扫描：

./tscancode --xml func.cpp 2>result.xml

输出报告 result.xml：

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <error file="func.cpp" line="7" id="nullpointer" subid="dereferenceAfterCheck" severity="error"
           msg="Comparing [p] to null at line 3 implies [p] might be null. Dereferencing null pointer [p]." />
</results>

4.2 常用命令参数

# 扫描单个文件，输出 XML
./tscancode --xml your_code.cpp 2>result.xml

# 扫描整个目录（递归，用法以 --help 为准）
./tscancode --xml ./src/ 2>result.xml

# 查看全部参数
./tscancode --help

错误报告字段说明：file 文件、line 行号、id 检查规则编号、subid 子规则、severity 严重级别、msg 缺陷描述。

常见检查规则（id 命名）举例：

完整规则清单随 GUI 规则包展示，以编译版本内置规则为准。

4.3 多语言示例与扫描命令

仓库内置示例代码：

• C++ 示例：samples/cpp
• C# 示例：samples/csharp
• Lua 示例：samples/lua

建议新用户先跑通示例，再把规则套到自己的工程上。

各语言扫描命令示例：

# C++ 单文件
./tscancode --xml your_cpp.cpp 2>cpp_result.xml

# C++ 目录
./tscancode --xml ./src 2>cpp_result.xml

# Lua 脚本
./tscancode --xml your_script.lua 2>lua_result.xml

# C# 代码
./tscancode --xml your_code.cs 2>csharp_result.xml

具体各语言支持程度以编译版本与 CHANGELOG 为准（官方说明 trunk 当前以 CPP 为主）。

常用命令行参数：

完整参数列表以 tscancode --help 实际输出为准。

4.4 CI 流水线集成示例

以 GitLab CI 为例：

# .gitlab-ci.yml 片段
stages:
  - scan

static_scan:
  stage: scan
  script:
    - make -C tscancode   # 或使用预编译产物
    - ./tscancode --xml ./src 2>result.xml
    # 解析 result.xml，发现 error 级则退出码非 0
  artifacts:
    reports:
      junit: result.xml

要点：error 级缺陷阻断合并，warning 级仅归档；排除第三方代码目录；结果 XML 可转换为 junit 格式在流水线中可视化展示。

4.5 GUI 与规则定制

• 用 GUI 打开扫描结果，可在「规则包」面板中按需启停规则；
• 对确认是误报的缺陷，GUI 支持标记 false-positive，避免重复打扰；
• 开发自定义检查规则：基于 TscanCode 引擎扩展自己的 checker。

规则定制流程：

1. 先用默认规则全量扫描一次存量代码，建立基线（baseline）；
2. 在 GUI 规则包中逐条审视误报率高的规则，关闭不适用项；
3. 把团队确认的规则配置导出归档，纳入 Git 版本管理；
4. 每次扫描对比基线，只看新增缺陷（增量扫描思路）。

规则配置文件说明： 仓库 trunk/cfg 目录存放规则相关配置，具体格式以仓库内文件注释为准；GUI 规则包的启停状态可导出复用。

4.6 版本演进（官方 Highlights）

完整变更记录见 CHANGELOG.md。

4.7 报告解读示例

以 4.1 的空指针示例为例，result.xml 中每条 <error> 对应一个缺陷：

• id="nullpointer" subid="dereferenceAfterCheck"：规则与子规则编号，用于团队统计高频问题；
• severity="error"：严重级别，CI 中可按级别分级处理；
• msg 描述：解释缺陷成因（「第 3 行把 p 与 NULL 比较，说明 p 可能为空，却在此处解引用」）。

建议团队定期汇总 msg 模式，识别共性编码问题，针对性做 Code Review 培训。

XML 报告结构示意：

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <error file="func.cpp" line="7" id="nullpointer" subid="dereferenceAfterCheck"
           severity="error" msg="..." />
    <!-- 更多 error 节点 -->
</results>

可写脚本解析 <error> 节点，按 severity/文件聚合，生成团队质量看板。

4.5 适用场景

• C/C++ 业务代码提交前本地快速自查；
• CI 流水线集成：扫描不通过则阻断合并；
• 嵌入式/游戏 Lua 脚本质量检查；
• 存量代码库批量缺陷摸底。

五、常见问题排查（FAQ）

Q1：make 编译失败（g++ 版本太低） - 原因：需要 g++ 4.6+ 的 C++11 支持。 - 解决：升级编译器；若编译器不支持 nullptr，可在代码中引入 lib/cxx11emu.h 做模拟。

Q2：扫描大文件很慢 - 原因：单文件过大或目录递归过深。 - 解决：按模块分目录扫描；TscanCode 本身性能约 20 万行/分钟，必要时排除第三方依赖目录。

Q3：报告里误报太多 - 原因：部分规则对业务代码不适用。 - 解决：用 GUI 规则包关闭不适用规则；对确认误报逐条标记 false-positive。

Q4：C# / Lua 版本在哪里？ - 说明：官方 README 明确说明 trunk 目录当前仅为 CPP 版本，C# 与 Lua 版本处于内部 review 流程；Lua 支持已在 v2.15.01/02 中逐步提供（以 CHANGELOG 为准）。

Q5：没有 release 包，怎么获取可执行文件？ - 解答：官方未提供预编译 release，需按本文档第三章从源码编译；编译产物即为可直接运行的扫描器。

Q6：如何接入 CI？ - 解答：在流水线中执行 ./tscancode --xml <src> 2>result.xml，解析 XML 结果，发现 severity=error 则失败；可结合 junit 格式转换插件展示。

Q7：Windows 下编译出的 GUI 打不开 - 原因：未用 Release 配置，或缺少运行时库。 - 解决：Visual Studio 中切到 Release x64 重新生成；确认 VC++ 运行时已安装。

Q8：扫描结果中文件路径不对 - 原因：相对路径基准问题。 - 解决：在项目根目录执行扫描，或按绝对路径传入文件。

Q9：C# 代码扫描结果很少 - 原因：官方 README 说明 trunk 当前主要为 CPP 版本，C# 与 Lua 能力在持续完善中。 - 解决：以 CHANGELOG 为准；C# 项目可结合 Roslyn 等其他工具互补。

Q10：编译时提示 tinyxml 相关错误 - 原因：内置 tinyxml 源码未正确编译。 - 解决：确认按 README 全量 make，不要单独编译某个目录；清理 build 产物后重试。

Q11：扫描速度比官方宣称的慢 - 原因：扫描了第三方代码、大文件或重复目录。 - 解决：排除 vendor/、build/ 目录；按模块分批扫描；20 万行/分钟是官方标称性能，实际以硬件与代码复杂度为准。

Q12：GUI 与 CLI 结果不一致 - 原因：规则包配置不同。 - 解决：核对 GUI 规则包启停项与 CLI 默认规则是否一致；导出 GUI 配置对齐 CLI。

六、部署注意事项与最佳实践

1. 版本锁定：每次拉取代码记录 commit hash，团队内统一编译同一版本。
2. 规则裁剪：不要全规则开启，先按团队误报率逐步收敛规则集。
3. CI 分级：error 级阻断合并，warning 级仅记录，避免流水线过严。
4. 第三方代码排除：扫描时排除 vendor/、第三方库目录，减少噪音。
5. GUI 归档：用 GUI 维护团队的误报标记与规则包配置，纳入版本管理。
6. 合规注意：TscanCode 本体为 GPL-3.0 协议，二次开发/分发需遵守 GPL 条款；内置 tinyxml 为 zlib 协议。
7. 增量扫描：对存量大项目先全量建基线，之后只对新增/改动代码做阻断式扫描。
8. 定期维护规则：随版本升级重新评估规则集，v2.15.x 对 Lua 有大量修复，Lua 项目建议升级到最新版。
9. 结果留存：每次扫描的 XML 报告归档，用于趋势对比（缺陷总数是否下降）。

七、参考资料

• GitHub 仓库：https://github.com/Tencent/TscanCode
• 更新日志：https://github.com/Tencent/TscanCode/blob/master/CHANGELOG.md
• C++ 示例：https://github.com/Tencent/TscanCode/tree/master/samples/cpp
• C# 示例：https://github.com/Tencent/TscanCode/tree/master/samples/csharp
• Lua 示例：https://github.com/Tencent/TscanCode/tree/master/samples/lua