网页应用智能脚本注入

🚀 框架感知的开发环境脚本注入工具

支持 Vite、Next.js、React 等现代框架的智能脚本注入，提供零侵入式的开发期监控方案。

🌟 特性

框架感知注入

• 🟢 Vite: 自动注入 Vite 插件到 vite.config.js
• 🟢 Next.js App Router: 注入到 app/layout.tsx
• 🟢 Next.js Pages Router: 注入到 pages/_document.tsx
• 🟢 Create React App: 注入到 public/index.html
• 🟢 传统 HTML: 直接修改 HTML 文件

核心功能

• ✅ 支持远程 URL 和绝对路径注入
• ✅ 自动检测项目类型和最佳注入方式
• ✅ 智能去重，避免重复注入
• ✅ 支持卸载功能
• ✅ 预览模式（dry-run）
• ✅ 详细日志输出
• ✅ 零侵入式修改

安装

使用 npx（推荐）：

# 查看帮助信息
npx @xagi/dev-inject --help

# 查看版本信息
npx @xagi/dev-inject --version

# 静默安装（自动确认，无需交互）-y 选项
npx -y @xagi/dev-inject install --framework

或使用 pnpm dlx：

pnpm dlx @xagi/dev-inject --help

🚀 快速开始

框架感知注入（推荐）

# 静默安装（推荐，无需确认）
npx -y @xagi/dev-inject install --framework

# 使用默认脚本地址 (/sdk/dev-monitor.js)
npx @xagi/dev-inject install --framework

# 或指定自定义地址
npx @xagi/dev-inject install --remote=http://localhost:9000/dev-monitor.js --framework

# 使用 pnpm
pnpm dlx @xagi/dev-inject install --framework

# 查看检测到的项目类型
npx @xagi/dev-inject install --framework --verbose

传统 HTML 注入

# 注入远程脚本
npx @xagi/dev-inject install --remote=http://localhost:9000/dev-monitor.js

# 注入本地脚本
npx @xagi/dev-inject install --remote=/scripts/dev-monitor.js

# 指定特定文件
npx @xagi/dev-inject install --remote=/scripts/monitor.js --file=./public/index.html

预览和卸载

# 预览将要执行的操作
npx @xagi/dev-inject install --remote=/scripts/monitor.js --framework --dry-run

# 移除框架注入
npx @xagi/dev-inject uninstall --framework

# 移除传统注入
npx @xagi/dev-inject uninstall

📋 支持的脚本格式

远程 URL

--remote=http://localhost:9000/dev-monitor.js
--remote=https://cdn.example.com/monitor.js

绝对路径

--remote=/scripts/dev-monitor.js
--remote=/assets/monitor.js

🎯 配置选项

选项	描述	示例
--remote	脚本地址（可选，默认值: /sdk/dev-monitor.js）	--remote=/scripts/dev-monitor.js
--framework, -f	使用框架感知注入	--framework
--file	指定 HTML 文件	--file=./public/index.html
--dry-run	预览模式	--dry-run
--verbose	详细输出	--verbose
--help	显示帮助	--help
--version	显示版本	--version

监控脚本功能

dev-inject/scripts/dev-monitor.js 提供完整的开发监控功能：

错误监控

• 全局 JavaScript 错误捕获
• Promise Rejection 监控
• 资源加载错误监控
• iframe 通信错误

性能监控

• 页面加载时间分析
• 网络请求时间统计
• 长任务检测
• DOM Ready 性能

开发工具

• 实时监控面板
• 数据导出功能
• 控制台日志拦截
• iframe 通信支持

使用监控面板

// 在浏览器控制台执行
DevMonitor.showPanel();    // 显示监控面板
DevMonitor.getData();      // 获取监控数据
DevMonitor.exportData();   // 导出监控数据
DevMonitor.clearData();    // 清除监控数据

配置选项

选项	描述	示例
--remote	脚本地址（必需）	--remote=/scripts/dev-monitor.js
--file	指定 HTML 文件	--file=./public/index.html
--dry-run	预览模式	--dry-run
--verbose	详细输出	--verbose
--help	显示帮助	--help
--version	显示版本	--version

工作原理

1. 查找 HTML 文件：自动查找项目中的 HTML 文件（优先 index.html）
2. 脚本注入：在 </head> 标签前注入脚本
3. 去重处理：移除之前注入的相同脚本，避免重复
4. 智能检测：支持多种项目结构（React、Vite、Next.js 等）

开发和测试

# 进入项目目录
cd dev-inject

# 安装依赖
npm install

# 链接到全局（用于本地测试）
npm link

# 测试帮助信息
dev-inject --help

# 测试注入功能（预览模式）
dev-inject install --remote=/scripts/dev-monitor.js --dry-run

# 取消链接
npm unlink

📦 发布到 npm

# 确保你已经登录 npm
npm login

# 发布到 npm
npm publish

# 发布后验证
npx @xagi/dev-inject --version

项目结构

dev-inject/
├── bin/
│   └── index.js              # CLI 入口文件
├── lib/
│   ├── args.js               # 参数解析
│   ├── inject.js             # 核心注入功能
│   ├── utils.js              # 工具函数
│   └── help.js               # 帮助信息
├── scripts/
│   └── dev-monitor.js        # 监控脚本
├── package.json              # 项目配置
└── README.md                 # 说明文档

兼容性

• ✅ Node.js >= 14.0.0
• ✅ 所有现代浏览器
• ✅ React、Vue、Angular、Next.js 等
• ✅ Vite、Webpack、Create React App 等构建工具

📦 发布配置

本项目已配置 npm publish 时仅包含必要的文件：

包含的文件：

• ✅ bin/ - CLI 可执行文件
• ✅ lib/ - 核心库文件
• ✅ scripts/ - 监控脚本
• ✅ *.md - 文档文件
• ✅ LICENSE - 许可证

排除的文件：

• ❌ test/ - 测试文件
• ❌ test-projects/ - 测试项目
• ❌ 所有 *.test.js 文件
• ❌ 测试和演示 HTML 文件
• ❌ 日志和缓存文件
• ❌ 开发工具配置

完整配置请查看 package.json 的 files 字段和 .npmignore 文件。

注意事项

1. 绝对路径：确保静态文件服务器可以访问该路径
2. 重复注入：工具会自动处理重复注入问题
3. 权限：确保有 HTML 文件的写入权限
4. 备份：建议在操作前备份重要文件

许可证

MIT