Docfx中FilterConfig配置不生效问题排查求助

当前配置与问题 #

1. filterConfig.yml 配置 #

apiRules:
- exclude:
  uidRegex: ClassLibrary1
  type: Namespace

2. docfx.json 中 metadata 配置 #

"metadata": [
    {
      "src": [
        {
          "files": [
            "**/*.csproj"
          ]
        }
      ],
      "dest": "api",
      "filter": "filterConfig.yml"
    }
  ],

3. 项目结构 #

根目录下存放docfx.json与filterConfig.yml，解决方案包含WebApplication1和ClassLibrary1两个项目。

4. 问题现象 #

生成的API文档中仍显示ClassLibrary1命名空间，filter规则未生效。

排查与修复方案 #

1. 修正正则表达式匹配规则 #

Docfx中命名空间的UID为完整命名空间名称，原正则可能未精确匹配。尝试以下两种写法：

• 精确匹配根命名空间：

apiRules:
- exclude:
  uidRegex: ^ClassLibrary1$
  type: Namespace

• 匹配所有以ClassLibrary1开头的命名空间（含子命名空间）：

apiRules:
- exclude:
  uidRegex: ^ClassLibrary1
  type: Namespace

2. 验证filter文件路径 #

确认filter字段的路径相对于docfx.json的位置是否正确。若两者在同一目录则无需调整，但执行docfx metadata时需留意控制台是否出现"找不到filter文件"的警告。

3. 清理缓存后重新生成 #

Docfx会缓存metadata，旧缓存可能导致规则不生效，执行以下命令彻底重建：

docfx clean
docfx metadata
docfx build

4. 检查命名空间实际UID #

先生成未过滤的metadata，打开api目录下的ClassLibrary1.yml文件，查看开头的uid字段（例如是否为ClassLibrary1.ClassLibrary1这类带程序集后缀的格式），根据实际UID调整正则表达式。

5. 替换为fullNameRegex规则 #

部分场景下，使用fullNameRegex匹配命名空间全名更可靠：

apiRules:
- exclude:
  fullNameRegex: ^ClassLibrary1$
  type: Namespace

6. 升级Docfx版本 #

尝试升级至最新稳定版（如v2.76+），旧版本可能存在filter规则的已知bug。

内容的提问来源于stack exchange，提问作者Nefisto