简介：Source Counter 是一款面向软件开发团队、项目经理与代码质量分析人员的代码统计工具，可扫描多种编程语言源码，区分代码行、注释行与空行，并生成按文件或类细分的统计报告，用于量化开发工作量、评估项目进度与维护难度。压缩包共45个文件，约2.31MB，内含可执行程序、dll动态库、多语言语言包、ico图标、html报告模板及xml配置文件，另附32张png界面素材与少量jpg预览图，整体为可直接运行的Windows工具包。已有769人学习下载，说明其在代码规模盘点与项目汇报场景中具有一定参考价值。读者可借助报告模板和配置项自定义统计口径，结合注释比例、空行分布与复杂度指标，快速定位代码可读性和结构问题，为团队排期、资源分配和代码审查提供可复用的数据依据。

1. 一个新接手的仓库，先数清楚它有多大

接过一个跑了三年的老系统，交接文档只有两页，第一句写着「代码量不大」。真上手才发现，光前端目录就躺了四千多个文件，其中一半是构建产物。这种时候靠感觉判断规模很容易出问题——排期、报价、重构范围全建立在这个数字上。Source Counter 就是干这件事的一套本地代码统计工具，扫一遍目录，按语言把代码行、注释行、空行分开算清楚，结果能导成 JSON/CSV，也能当命令行插件挂进流水线卡阈值。它适合三类人：要出交付报告的、要评估重构成本的、要盯住新增代码别失控的。下面从我自己的口径表讲起，一直讲到怎么把它塞进 CI。

2. 统计口径先对齐：代码行、注释行、空行到底怎么算

两个人拿同一个仓库跑出两个数，九成不是工具坏了，是口径不同。开扫之前，三件事必须写进配置里固定下来：行怎么切、混合行归谁、语言怎么认。这三件事不定，后面所有报表都是悬空的。

2.1 物理行与逻辑行：两个数字能差出两成

物理行就是文件里换行符的个数，读一遍就能数完，代价几乎为零。逻辑行是语句数，一行里塞五个a=1;b=2;就算五条。前端项目走一次格式化，物理行能凭空涨三成；反过来，压缩过的产物文件一行几百个语句，物理行又严重低估。

Source Counter 默认输出物理行的三分法（代码、注释、空行），逻辑行是可选开关--count-mode=logical。我一般把物理行当唯一权威数字，逻辑行只在给人估工时做参考。这里有个边界要说清：如果团队把行数写进考核，一次prettier --write就能让指标集体上浮，问题不在工具，在拿物理行当 KPI 这件事本身。

2.2 注释归属：行尾注释到底算代码还是注释

块注释的边界相对好判：/*独占一行算注释，*/独占一行算注释，中间内容算注释，/* ... */跟在代码后面算代码行。真正麻烦的是行尾注释。

const retry = 3; // 重试三次，超过就抛错

这一行有三种记法：算一条代码行、单列一列mixed、或者按字符比例拆成 0.7 代码 + 0.3 注释。Source Counter 默认走第一种，同时把混合行的计数单独放在mixed字段里，需要第二种口径时打开--mixed=separate即可。

注意：混合行算代码行会让「注释率」系统性偏低。我踩过的坑是拿注释行 / 总行出过一次报表，前端组 3%、后端组 18%，看着像前端不写注释，实际是前端习惯行尾注释、后端习惯块注释。指标本身没错，是口径没解释清楚。

2.3 语言识别：扩展名表、双扩展名、shebang 的优先级

识别顺序建议固定成：精确文件名 → 双扩展名 → 单扩展名 → 首行 shebang → 兜底归类。精确文件名是为了Makefile、Dockerfile、.gitignore这类没有扩展名的东西；双扩展名是为了.d.ts、.blade.php、.min.js，这些文件如果只截最后一段就会被认成 TypeScript、PHP、JavaScript，但其实该单列或者直接排除。

# .sc.yml 里的一段语言映射覆盖 language_map: "Makefile": { language: make } "Dockerfile": { language: dockerfile } ".d.ts": { language: typescript, kind: declaration, exclude_from_report: true } ".min.js": { language: javascript, kind: generated, exclude: true } ".h": { language: c, ambiguous: [c, cpp] } ".m": { language: objc, ambiguous: [objc, matlab] } ".vue": { language: vue, embedded: [html, javascript, css] }

ambiguous这一项是给那些真的没法靠文件名判断的情况准备的，.h到底是 C 还是 C++，.m到底是 Objective-C 还是 MATLAB，只能靠团队约定。--ambiguous=first|split|skip三个取值分别对应「按列表第一个算」「两边各记一半」「单独归到 unknown」，我默认用first，因为它至少保证总数守恒，split会让数字出现小数，报表上很难看。

2.4 用一段轻量状态机把注释判断做对

正则在注释识别上是必翻车的：字符串里的//、URL 里的http://、正则字面量里的/*，全都会被误判成注释开头。吃过的亏是某次统计出一个模块注释率 60%，查了半天发现那是个存了一堆 URL 的配置文件。

正确做法是逐字符推进的状态机，状态至少要有：普通、行注释、块注释、单引号串、双引号串、模板串。

# 轻量注释/字符串状态机：逐字符推进，避免正则把字符串里的 // 当成注释 NORMAL, LINE, BLOCK, SQ, DQ, TPL = range(6) def scan(text, syntax): """syntax 由语言表注入：line_comment / block_open / block_close / quotes / escape""" state = NORMAL code = comment = blank = 0 line_has_code = line_has_comment = False i, n = 0, len(text) while i < n: ch = text[i] if ch == "\n": # 一行结束，结算归属 if not line_has_code and not line_has_comment: blank += 1 elif line_has_comment and not line_has_code: comment += 1 else: code += 1 # 混合行按代码行计，mixed 另行统计 line_has_code = line_has_comment = False if state == LINE: state = NORMAL i += 1 continue if state == NORMAL: if text.startswith(syntax["line_comment"], i): state = LINE; line_has_comment = True i += len(syntax["line_comment"]); continue if text.startswith(syntax["block_open"], i): state = BLOCK; line_has_comment = True i += len(syntax["block_open"]); continue if ch in syntax["quotes"]: state = {"'": SQ, '"': DQ, "`": TPL}[ch] line_has_code = True elif not ch.isspace(): line_has_code = True i += 1 elif state == LINE: i += 1 elif state == BLOCK: if text.startswith(syntax["block_close"], i): state = NORMAL; i += len(syntax["block_close"]) else: i += 1 else: # 字符串内部，转义符整体跳过 if ch == syntax.get("escape", "\\"): i += 2; continue if (state == SQ and ch == "'") or (state == DQ and ch == '"') or (state == TPL and ch == "`"): state = NORMAL i += 1 return {"code": code, "comment": comment, "blank": blank}

逻辑上分两段：状态机负责判断「这个字符属于代码、注释还是字符串内部」，结算器负责在一行结束时决定这一行归到哪一栏。line_has_code和line_has_comment两个布尔量是关键，它们记录的是同一行里有没有出现过代码字符和注释起始，最后按「有代码就算代码行」的规则结算。

参数上要留心的三处：escape默认是反斜杠，但 SQL 用两个单引号转义，语言表里必须覆盖；block_open/block_close对支持嵌套块注释的语言（比如某些函数式语言）要额外加一层深度计数，否则内层*/会提前结束；模板串里出现${}时，里面的内容严格说属于代码，简化实现一般按字符串处理，对行数统计影响很小，可以接受。做到这一步，99% 的文件能算对，剩下 1% 是宏和 heredoc，工程上没必要追。

3. 跑通第一次扫描：安装、排除规则和结果导出

口径定完就可以动手了。这一章按「装 → 排除 → 输出 → 加工」走一遍，每步都给出可以直接抄的命令和配置。

3.1 两种形态：命令行程序是主体，插件是壳

Source Counter 分两种形态：命令行程序和编辑器插件。命令行程序负责扫描和输出，是真正的功能主体；插件形态（侧边栏显示当前文件行数、提交前提示单文件超限）只是读取同一份配置，把结果就近展示。

# 解压后先看清单和校验和，别拿到包就直接跑 tar -tzf source-counter.tar.gz | head -20 sha256sum -c checksums.txt ./source-counter --version ./source-counter --selftest

第一条只是列目录，确认里面没有奇怪的可执行文件；第二条校验完整性；第三条打印版本，这个版本号后面会写进报表，是人复查时的线索；--selftest会跑一组内置的样例文件（含空行、块注释、字符串里的//、CRLF 混合换行），输出实际值与期望值，全部匹配才返回 0。我一般在新机器上先跑--selftest，它挂了后面所有数字都不用看。

如果想全局使用，把可执行文件放进 PATH 下的目录，或者建个软链；插件形态则在编辑器的设置里指向同一个可执行文件路径，保证两边口径一致。

3.2 排除规则：先把 node_modules 挡在门外

排除规则没配好，统计结果基本没有意义。一个node_modules能让 30 万行的项目报出 120 万行，后面所有分析都在错误的基础上进行。

# .sc.yml —— 建议和源码一起进仓库 scan: root: . exclude: - "**/node_modules/**" - "**/vendor/**" - "**/dist/**" - "**/build/**" - "**/*.min.js" - "**/*.pb.go" - "**/*_generated.*" - "**/*.lock" follow_symlinks: false max_file_size: 2MB binary_detect_bytes: 8000 jobs: 4

逐条说：exclude支持 gitignore 风格的通配，**匹配任意层级，写规则时宁可多排除几个目录，漏排一次代价远大于多排一次；follow_symlinks: false是防止软链指回上级目录造成无限递归，这是最容易卡死的一个开关；max_file_size挡住 sql dump、日志、序列化数据这类超大文件，设成 2MB 能覆盖绝大多数真实源码文件；binary_detect_bytes是二进制嗅探的取样字节数，程序读文件头部这段，发现 NUL 字节就判定为二进制跳过；jobs是并行 worker 数，别一上来就开到 CPU 核数，内存会翻倍。

不想维护两份规则的话，打开--use-gitignore让工具顺带读取仓库里的.gitignore，但注意.gitignore里通常不会有dist/（很多团队把构建产物也提交了），这种还是要靠.sc.yml补。

3.3 输出字段：JSON 里到底装了什么

./source-counter scan --config .sc.yml --format json --out report.json

{ "schema": 1, "tool_version": "x.y.z", "config_hash": "…", "totals": { "files": 0, "physical": 0, "code": 0, "comment": 0, "blank": 0, "mixed": 0 }, "by_language": [ { "language": "python", "files": 0, "code": 0, "comment": 0, "blank": 0 } ], "by_directory": [ { "path": "src/api", "code": 0 } ], "files": [ { "path": "src/main.py", "language": "python", "code": 0, "comment": 0, "blank": 0 } ], "skipped": { "binary": 0, "too_large": 0, "excluded": 0, "unreadable": 0 } }

关键字段的用途：schema和tool_version保证结果可追溯，两个人跑出不同数字时先比这两个；totals里四个分项加mixed必须等于physical，不等就是统计器有 bug 或者文件在扫描过程中被改了；by_directory是按目录层级聚合好的，做交付报告时直接取；skipped是最容易忽略但排查时最有用的一个，too_large突然涨到几百，说明目录里混进了数据文件，unreadable不为零就是权限问题，binary异常高通常是编码踩坑（下一章细说）。

3.4 用 Python 把 JSON 变成一张可交付的表

原始 JSON 给不了人看，落到报告里还得按顶层目录聚合一次，顺手做行数守恒校验。

import json, collections, pathlib report = json.loads(pathlib.Path("report.json").read_text(encoding="utf-8")) t = report["totals"] # 行数守恒校验：四个分项之和必须等于物理行总数 assert t["code"] + t["comment"] + t["blank"] + t.get("mixed", 0) == t["physical"], "行数不守恒" agg = collections.Counter() for d in report["by_directory"]: top = d["path"].split("/")[0] or "." # 只看第一级目录 agg[top] += d["code"] print(f"| 顶层目录 | 代码行 | 占比 |") print(f"|---|---|---|") for name, code in agg.most_common(): print(f"| {name} | {code} | {code / max(t['code'], 1):.1%} |") print(f"\n跳过明细：{report['skipped']} 数据版本：{report['tool_version']}")

逻辑说明：先做守恒校验再做聚合，顺序不能反——不守恒的结果聚合出来一样是错的，早失败早发现。max(t['code'], 1)是防除零，空仓库扫出来code为 0 时脚本不应该崩。参数上唯一要按项目改的是split("/")[0]，如果代码放在packages/下（多包仓库），这里要改成取前两段，不然所有包都会挤成一行。跑出来的 Markdown 表直接贴进交付文档，比截图数字有说服力得多。

4. 避坑与排查：五条把统计跑出问题的记录

这一章全是踩过的坑，按「现象 → 原因 → 解决」写，遇到类似症状可以直接对照。

4.1 结果偏大：重复文件、符号链接与构建产物

现象：仓库实际三十多万行，扫出一百二十万行，by_directory里某些目录行数明显不合理。

原因有三类：一是dist/、build/里的压缩产物和源码同时存在，被算了两遍；二是软链指回上级目录，同一份文件在不同路径下被重复计入；三是目录里带进来的第三方源码（比如vendor/下整个框架），本来就不该算进自研代码。

解决：exclude里补dist、build、vendor、third_party；开follow_symlinks: false；再给一层保险，打开按 inode 去重（同一文件多个硬链或软链只算一次）。判断有没有重复，最快的办法是对比totals.files和find . -type f | wc -l，前者明显大于后者就是重复计入。

4.2 结果偏小：编码和二进制嗅探误判

现象：某个老模块扫出来 0 行，by_language里干脆没有这个语言。

原因：老文件是 GBK 编码，文件头几千字节里恰好有0x00字节，被二进制嗅探规则判成二进制跳过；也可能是 UTF-16 带 BOM 的文件，字节序标记直接被当成 NUL；还有一种少见情况是文件权限不对，读失败进了unreadable。

解决：先看skipped明细，binary计数对得上就是这个原因。然后把binary_detect_bytes调大（比如 32000），再给这些扩展名加白名单binary_whitelist: [".c", ".h", ".sql"]。编码层面开--encoding=auto，让工具做 BOM 和字节模式检测，读失败时降级成 latin-1 兜底——行数统计只关心换行符位置，字符解码错了也能数对，这是这个场景下唯一可以放松的地方。

4.3 注释率离谱：模板文件和内联脚本

现象：一个 .vue 项目报出 40% 的注释率，人工抽查怎么也对不上。

原因：单文件组件里<template>段的 HTML 注释（<!-- -->）被算进了注释行，而<script>段的代码被记成了同一种语言；.html同理，内联的<script>和<style>全被压在一个语言下面，注释符号表只能用一套。

解决：打开分片模式--split-embedded，让工具按<template>、<script>、<style>把文件切成三块，各自套用自己的语法规则，然后在by_language里分别出现 html / javascript / css 三条。如果只是想要一个干净的总数，另一种做法是把这类模板文件整体从注释率报表里剔除，只统计纯逻辑文件——我的建议是分片，因为总量统计不受影响，还多拿到一份按语言的细分。

4.4 扫描卡死或内存飙升

现象：进度停在一个文件上不动，内存从几百 M 涨到几 G，最后被系统杀掉。

原因：单个两三百兆的 sql dump 被整个读进内存再做字符扫描；并行 worker 数开得太多，每个 worker 都持有一份大文件缓冲区；软链环路导致同一目录被反复遍历。

解决：max_file_size设成 2MB 挡住绝大部分；jobs先从 2 开始，观察内存再往上加；大文件其实是需要统计的场景（比如那些 sql），单独用--large-file=stream走流式扫描，一次只读一行，内存恒定。真要定位是哪个文件卡住，加--progress=verbose，它会打印当前正在处理的路径，最后一行就是嫌疑文件。

4.5 数字对不上：版本漂移和配置漂移

现象：同一个 commit，两个人跑出两个结果，差几百行。

原因：工具版本不同，不同版本对某个扩展名的默认归类、对.gitignore的读取行为都可能变；配置没进仓库，各自在自己机器上改了.sc.yml；扫描根目录不同（一个在仓库根，一个在子目录）。

解决：报表里固定写入tool_version和config_hash，两个数字不一致就不用往下比了；.sc.yml必须进版本库，和代码一起评审；命令里显式带--config .sc.yml和--root .，不依赖默认值。这条看着是流程问题，但它导致的返工比前面四条加起来都多。

5. 混合项目与门禁：把统计结果变成能卡人的阈值

统计出数字只是第一步，真正有价值的是把它变成一条能拦提交的规则。这一章讲三件事：混合文件怎么拆、增量怎么算、阈值怎么定。

5.1 一个文件里三种语言：分片统计的边界

现代项目里「一个文件一种语言」早就不成立了。.vue有模板、脚本、样式；.html有内联脚本；.md里有代码块；.tsx里混着 JSX 和 TypeScript。

分片统计的做法是按标记切段再分别计数，配置里可以显式声明：

embedded_rules: - glob: "**/*.vue" segments: - { open: "<template>", close: "</template>", language: html } - { open: "<script", close: "</script>", language: javascript } - { open: "<style", close: "</style>", language: css } - glob: "**/*.md" segments: - { fence: "```", language: auto } # 围栏代码块按标注语言识别

参数说明：open只要写起始标记的前缀即可，属性（比如<script setup lang="ts">）由解析器忽略；fence: "```"表示按围栏块切，language: auto会读围栏后面的语言标注，没标注就落到unknown。边界在嵌套上——模板里再嵌一个<template>的情况极少但存在，实现里一般只认第一层闭合标记，遇到嵌套会切错，这种文件占比通常不到千分之一，接受即可。

分片之后by_language会多出几条，总量保持守恒，这是判断分片有没有做对的最直接办法。

5.2 增量统计：只算这次改了多少

全量统计适合出报告，卡提交必须用增量，否则一个历史包袱重的仓库永远过不了门禁。

# 三点 diff：只取当前分支相对公共祖先新增/修改/重命名的文件 git diff --name-only origin/main...HEAD --diff-filter=ACMR > changed.txt wc -l < changed.txt # 只统计这些文件，输出到 delta.json ./source-counter scan --config .sc.yml --files-from changed.txt \ --format json --out delta.json --jobs 2

--diff-filter=ACMR四个字母分别对应新增、删除、修改、重命名，删除文件必须排除掉，否则--files-from会报找不到路径；重命名保留，因为它是「旧文件消失 + 新文件出现」，在增量里算作新增更符合直觉。三点 diff（origin/main...HEAD）比两点 diff 更准，它比的是两条分支的公共祖先，不会被主干上的无关提交干扰。

--files-from的行为是「只扫清单里的文件，但排除规则照常生效」，所以changed.txt里混进来的dist/产物还是会按.sc.yml的规则被跳过，这一点很重要。

5.3 CI 里的阈值怎么定：三条能落地的规则

阈值定太严全组骂，定太松等于没有。我的经验是只上三条，且都能给出解释。

前两条落到流水线上长这样：

- name: code-size-gate run: | source-counter scan --config .sc.yml --files-from changed.txt \ --format json --out delta.json --jobs 2 python ci/gate.py

import json, sys delta = json.load(open("delta.json", encoding="utf-8")) NEW_LINE_LIMIT = 500 FILE_LINE_LIMIT = 800 new_code = delta["totals"]["code"] big_files = [f for f in delta["files"] if f["code"] > FILE_LINE_LIMIT] if new_code > NEW_LINE_LIMIT: print(f"[提示] 本次新增代码 {new_code} 行，超过 {NEW_LINE_LIMIT} 行，建议拆分提交") if big_files: for f in big_files: print(f"[报警] 单文件超限：{f['path']} = {f['code']} 行") sys.exit(1) # 单文件超限才真的拦 print(f"通过：新增 {new_code} 行，涉及 {delta['totals']['files']} 个文件")

逻辑上做了个区分：新增总量超限只打印提示，退出码仍然是 0，不卡流水线；单文件超限才exit 1。这个区分是有原因的——一次大重构新增八百行完全正常，硬拦会逼人用奇怪的方式绕过；而一个文件突然涨到两千行，基本可以确定是复制粘贴没拆。参数上调这里就能改行为，FILE_LINE_LIMIT按团队实际代码风格定，老仓库可以放到 1200，新项目收紧到 500 都不过分。

5.4 基线：别让历史包袱挡住新提交

历史包袱重的仓库，全量数字永远超标，门禁只能管增量。做法是存一份基线快照，每次只比变化量。

# 基线在主分支合并时刷新，只在主干跑 ./source-counter scan --config .sc.yml --format json --out baseline.json

基线文件入库或者放对象存储都行，关键是要带tool_version。跨版本比较时如果tool_version变了，得先用新版本重刷一次基线再比，否则差异里混着工具行为变化，排查起来极其难受。我在一个项目上就吃过这个亏：升级工具后增量报表连续两周显示「新增代码 3000 行」，实际代码一行没动，是新版本对某个扩展名的归类变了。

6. 进阶：把一次统计变成一条趋势曲线

单次统计回答「现在多大」，趋势才回答「在往哪个方向走」。这一步不需要额外工具，只要把每次结果按时间落下来。

6.1 每周落一个快照

定时任务里跑一次全量，文件名带日期和短哈希，扔进一个固定目录：

DATE=$(date +%Y%m%d) SHA=$(git rev-parse --short HEAD) ./source-counter scan --config .sc.yml --format json \ --out "snapshots/report-${DATE}-${SHA}.json"

文件名里带哈希是为了在数字异常时能精确回到那个提交重跑。快照目录要定期清理，但至少保留最近三个月，趋势看季度粒度足够了。

6.2 三个值得盯的比值

原始行数看久了会麻木，下面三个比值更能提前暴露问题：

第一个指标我最看重。行数总量涨，可能是业务在长；P90 涨，说明单个文件的复杂度在失控，这个数字的恶化通常比线上故障早三到六个月。

6.3 一个我坚持的小动作

每次发版前跑一遍--selftest，再跑一次全量统计，把report.json和版本号一起归档。这个习惯是被坑出来的：有次发版后两周，需要回溯某个模块的规模变化，翻遍记录只有一张截图，连是哪个提交都不知道，最后靠人工git log一个个数。自那以后我每次出交付报告，都强制走一遍「自检 → 全量 → 归档」三步，tool_version和config_hash跟着报告一起存，谁再问「这个数怎么来的」直接甩文件路径。统计工具本身不复杂，值钱的是口径稳定、结果可追溯这两件事。希望帮到你。

本文还有配套的精品资源，点击获取