企业官网建设流程全解析

Knip report

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

Unused devDependencies (2)

它表达的信息非常明确：在 `app-example-plugin` 这个包的源码分析中，[packages/app-example-plugin/package.json](https://link.gitcode.com/i/379a9271e44e28c6d1068e16e30cafef) 的 `devDependencies` 里有 2 个依赖从未被任何入口文件、测试或 Storybook 文件引用，因此被标记为“Unused devDependencies”，严重级别为 `error`： | 依赖 | 报告位置 | 说明 | | :---- | :------- | :---- | | `cross-fetch` | `package.json:51:6` | 定位到 package.json 第 51 行第 6 列，与当前文件中 `devDependencies.cross-fetch`（`^4.0.0`）的声明位置一致 | | `msw` | `package.json:52:6` | 报告记录为第 52 行第 6 列；值得注意的是，当前 [package.json](https://link.gitcode.com/i/379a9271e44e28c6d1068e16e30cafef) 的 `devDependencies` 中已不存在 `msw` 这一项，说明报告反映的是某次生成时的依赖快照，后续若依赖清单发生变化而未重新生成报告，CI 校验会失败（后文详述） | 这里的 `package.json:51:6` 这类“行:列”定位是 Knip 的 Markdown reporter 输出的一部分，方便开发者直接跳转到 `package.json` 中对应的依赖声明处进行确认或删除。 ## 二、报告从何而来：`yarn build:knip-reports` 命令 在仓库根目录的 [package.json](https://link.gitcode.com/i/ecffd44f617d10116fad3a4afd161348) 中定义了生成所有 Knip 报告的脚本： ```json "build:knip-reports": "backstage-repo-tools knip-reports"

它调用的backstage-repo-tools是工作区内部包 @backstage/repo-tools。命令行入口注册在 packages/repo-tools/src/commands/index.ts：

program .command('knip-reports [paths...]') .option('--ci', 'CI run checks that there is no changes on knip reports') .description('Generate a knip report for selected packages') .action(lazy(() => import('./knip-reports/knip-reports'), 'buildKnipReports'));

命令的用法（见 packages/repo-tools/src/commands/knip-reports/knip-reports.ts 中打印的 TIP 提示）：

• 不带参数：yarn build:knip-reports—— 对packages/*与plugins/*下所有工作区包生成报告，并额外打印一条针对部分包的提示信息；
• 指定路径：yarn build:knip-reports packages/app-example-plugin（也支持packages/config packages/core-plugin-api plugins/*这样的多个路径/通配）；
• 附加--ci：进入 CI 模式，不再写文件，而是“报告必须与已提交内容完全一致，否则失败”（见下文第四节的分支逻辑）。

buildKnipReports函数本身的职责很轻量：通过resolvePackagePaths解析出目标包目录列表，然后委托给runKnipReports执行，任何异常都会以process.exit(1)结束。

三、生成机制源码解析：knip-extractor.ts

核心实现在 packages/repo-tools/src/commands/knip-reports/knip-extractor.ts。可以把它拆成四个环节来看。

1. 动态生成 Knip 配置（L56-L88）

generateKnipConfig会在仓库根目录写入一个临时的knip.json（结束后由cleanKnipConfig删除），其结构针对 Backstage 的工作区布局做了定制：

const knipConfig: KnipConfig = { workspaces: { '.': {}, '{packages,plugins}/*': { entry: ['dev/**/*.{ts,tsx}', 'src/index.{ts,tsx}'], ignore: [ '.eslintrc.js', 'config.d.ts', 'knexfile.js', 'node_modules/**', 'dist/**', '{fixtures,migrations,templates}/**', 'src/tests/transforms/__fixtures__/**', // cli packaging tests ], }, }, jest: { entry: ['src/setupTests.ts', 'src/**/*.test.{ts,tsx}'], }, storybook: { entry: 'src/components/**/*.stories.tsx' }, ignoreDependencies: [ // these is reported as a referenced optional peerDependencies // TBD: investigate what triggers these '@types/react', '@types/jest', '@internal/.*', // internal packages are not published and inlined '@backstage/cli', // everything depends on this for its package.json commands '@backstage/theme', // this uses `declare module` in .d.ts so is implicitly used whenever extensions are needed ], };

几个值得注意的设计决策：

• 入口规则：每个包的入口被认定为dev/**/*.{ts,tsx}与src/index.{ts,tsx}。以app-example-plugin为例，其 package.json 中main/types均指向src/index.ts，与这条规则一致。因此 Knip 只会从这些入口出发做引用可达性分析——凡是从入口、测试与 stories 都走不到的依赖，就会被判为“unused”。这也正是cross-fetch、msw这类“历史上用于测试、后来测试方式改变”的依赖会被点名的原因：它们不在任何 import 图里。
• jest / storybook 入口：测试文件（src/**/*.test.{ts,tsx}、src/setupTests.ts）和组件 stories 都算作入口，保证“只被测试用到的依赖”不会被误报为未使用。
• ignoreDependencies 白名单：@backstage/cli、@backstage/theme、@types/react等被显式豁免，注释中给出了理由（如@backstage/theme通过.d.ts中的declare module被隐式使用）。白名单中没有任何一项覆盖cross-fetch或msw，所以二者被如实报告。

2. 单包执行 Knip 与 CLI 参数（L96-L120）

handlePackage对每个包执行仓库根node_modules/knip/bin/knip.js，关键参数如下：

let report = await run( `${knipDir}/knip.js`, '-W', // Run the desired workspace packageDir, '--config', 'knip.json', '--no-exit-code', // Removing this will end the process in case there are findings by knip '--no-progress', // Remove unnecessary debugging from output // TODO: Add more checks when dependencies start to look ok, see https://knip.dev/reference/cli#--include '--include', 'dependencies,unlisted', '--reporter', 'markdown', );

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage