mp-lens 是一款专为微信小程序开发者设计的命令行工具，基于依赖分析，一键发现并清理未使用的文件与代码，帮助您安全瘦身并优化项目。

它聚焦清理相关场景：快速清理冗余、精准优化包体积，并辅助理解项目结构与提升代码质量。

通过一条命令立即体验清理（默认仅预览，实际删除前会有确认提示，可放心试用）：

npx mp-lens clean

---

✨ 功能特性

• 全面的依赖分析: 为安全清理提供可靠依据；扫描多种文件类型（.js, .ts, .wxml, .wxss, .less,.json,.wxs, 及常见图片格式），构建项目依赖图。
• 依赖图可视化: 生成交互式 HTML 或 JSON 格式的依赖图，清晰展现页面、组件、脚本间的相互联系。
• 精准的未使用文件检测: 基于依赖分析，准确识别项目中未被任何地方引用的孤立文件。
• 灵活的路径别名支持: 智能解析 TypeScript 路径别名 (Path Aliases) 和自定义别名配置。
• 广泛的项目结构兼容: 支持自定义小程序项目根目录、miniappRoot 和入口文件路径。
• 安全至上的清理机制:
  • 默认在删除文件前进行交互式确认。
  • 支持 Glob 模式，可在分析和清理时排除特定文件或目录。
• 代码质量检查（辅助清理）:
  • 检查组件声明与使用的一致性 (lint 命令)。
  • 清理 WXSS 文件中未使用的 CSS 规则 (purgewxss 命令)。
  • 检测重复代码 (cpd 命令)。
• 包体差异分析（清理前后对比）: 对比两个 Git 提交（分支或标签）之间的包体构成和大小差异 (diff 命令)。

安装（可选）

如需本地安装以获得更快的执行体验：

npm install --save-dev mp-lens
# 或者
yarn add --dev mp-lens

📖 命令详解

基本命令结构与示例：

mp-lens [全局选项] <命令> [命令特定选项]

将 <命令> 替换为以下之一：clean, graph, lint, purgewxss, diff, cpd。

mp-lens clean --write

全局选项

这些选项适用于所有命令：

• -p, --project <路径>: 指定项目的根目录 (默认: 当前执行命令的目录)。
• --miniapp-root <路径>: 指定小程序代码所在的子目录（相对于项目根目录）。如果未指定，工具会尝试自动检测（如 src, miniprogram）。
• --entry-file <路径>: 指定入口文件路径（相对于 miniappRoot，默认为 app.json）。
• --config <路径>: 指定配置文件的路径。
• --exclude <Glob模式>: 用于排除文件/目录的 Glob 模式。可多次使用此选项。
• --essential-files <文件1,...>: 指定应被视为"必要"的文件路径（相对于 miniappRoot），这些文件不会被报告为未使用。
• --include-assets: 在分析和清理中包含图片等资源文件 (默认不包含)。
• -v, --verbose: 显示更详细的日志输出，有助于调试。
• -h, --help: 显示帮助信息。

clean - 分析并移除未使用的文件

⚠️ 警告：此命令会修改或删除您的文件，请务必谨慎操作！

用法示例:

# 预览模式: 分析并列出未使用文件，然后提示确认删除
mp-lens clean

# 写入模式: 实际删除文件
mp-lens clean --write

# 清理时排除特定目录
mp-lens --exclude "**/legacy/**" clean

选项:

• --write: 实际写入更改（删除文件），不进行确认提示。

graph - 生成依赖关系图

用法示例:

# 生成交互式 HTML 依赖图
mp-lens graph

# 生成 JSON 格式的依赖图数据
mp-lens graph -f json -o dependency-data.json

选项:

• -f, --format <format>: 输出格式 (html|json)。默认为 html。
• -o, --output <file>: 保存图文件的路径。

lint - 检查组件声明与使用的一致性

分析 .json 声明与 .wxml 中的实际使用情况是否匹配。

# 分析整个小程序项目的组件使用情况
mp-lens lint

# 分析并尝试自动修复 JSON 文件中"声明但未使用"的组件
mp-lens lint --fix

选项:

• [path] (可选): 指定要分析的具体文件或目录。
• --fix: 自动从 .json 文件中移除"声明但未使用"的组件条目。

purgewxss - 清理 WXSS 文件中未使用的 CSS 规则

⚠️ 警告：此命令可能移除有用的 CSS，特别是在涉及复杂动态类名时。请务必仔细检查更改。

# 预览将移除的 CSS (不实际写入文件)
mp-lens purgewxss

# 实际写入更改 (谨慎使用!)
mp-lens purgewxss --write

选项:

• [wxss-file-path] (可选): 指定要分析的具体 WXSS 文件。
• --write: (高风险) 实际将优化后的 CSS 写入 .wxss 文件。

diff - 对比不同版本间的包体差异

分析并对比两个 Git 提交（分支或标签）之间的小程序包体构成和大小差异。

# 对比当前分支与 master 分支的包体差异
mp-lens diff --base master --target HEAD

选项:

• --base <分支/提交>: 指定对比的基准版本 (默认: master)。
• --target <分支/提交>: 指定对比的目标版本 (默认: HEAD)。

cpd - 代码重复检测 (Copy-Paste Detection)

检测项目中的重复或高度相似的代码片段。

# 在整个项目中执行代码重复检测
mp-lens cpd

⚙️ 配置文件

对于复杂或固定的配置，建议在项目根目录创建 mp-lens.config.js。

// mp-lens.config.js
module.exports = {
  miniappRoot: 'src',
  exclude: ['**/node_modules/**', '**/*.mock.js'],
  essentialFiles: ['utils/init.js'],
  aliases: {
    '@/*': ['src/*'],
  },
};

更多配置项请参考示例文件。

🔍 使用 Knip 进行深度分析 (可选)

Knip 是一个强大的未使用代码检测工具，可以识别未使用的导出、依赖项和死代码。根据项目类型，我们提供了不同的使用方案：

原生小程序项目

对于原生微信小程序项目，mp-lens 可与 Knip 集成，帮助 Knip 理解小程序特有的依赖关系（如 WXML、WXSS、组件声明等），实现更深层次的代码分析与清理。

详情请参阅：mp-lens 与 Knip 集成指南

uni-app 项目

对于基于 Vue 的 uni-app 项目，由于项目结构不同，无需使用 mp-lens，直接使用 Knip 即可。我们提供了针对 uni-app 的最佳实践配置：

在 uni-app 项目中使用 Knip

🤝 贡献

我们非常欢迎各种形式的贡献！如果您发现任何问题、有功能建议或希望改进代码，请随时提交 Issue 或创建 Pull Request。

📄 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。