# ChromeStorageMigrator

**Repository Path**: zpeakdev/ChromeStorageMigrator

## Basic Information

- **Project Name**: ChromeStorageMigrator
- **Description**: 在不同开发环境之间导出和导入 Storage 数据的 Chrome 扩展
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChromeStorageMigrator

一个用于在**不同开发环境之间导出和导入 localStorage 数据**的 Chrome 浏览器扩展。帮助开发者快速迁移网站本地存储数据，提升开发和调试效率。

## 📁 项目结构

```text
ChromeStorageMigrator/
├── manifest.json                # 扩展配置文件（Manifest V3）
├── popup.html                   # 插件弹出界面（含样式）
├── tsconfig.json                # TypeScript 编译配置
├── package.json                 # Node.js 项目配置
├── pnpm-lock.yaml               # pnpm 依赖锁定文件
├── src/
│   └── popup.ts                  # 主要功能逻辑
├── dist/                         # 编译输出目录（需构建生成）
│   └── popup.js
└── icons/                        # 扩展图标资源
    └── icon.png
```

## 🎯 核心功能

### 1. 文件导出/导入

| 功能 | 说明 |
|------|------|
| **📤 导出当前网站数据** | 将当前网站的 localStorage 保存为 JSON 文件下载 |
| **📥 导入数据到当前网站** | 从 JSON 文件导入数据到当前网站的 localStorage |

### 2. 剪贴板快速传输

| 功能 | 说明 |
|------|------|
| **📋 复制到剪贴板** | 将 localStorage 数据复制到剪贴板，便于快速分享 |
| **📋 从剪贴板粘贴** | 从剪贴板读取 JSON 并导入到当前网站 |

## 🔧 技术栈

| 配置项 | 说明 |
| :----- | :--- |
| **Manifest Version** | V3 (Chrome 扩展最新规范) |
| **TypeScript** | 5.9.3 |
| **编译目标** | ES2020 |
| **模块系统** | ESNext |
| **权限** | `activeTab`, `scripting` |
| **包管理器** | pnpm |

## 💻 工作原理

1. **脚本注入**: 使用 `chrome.scripting.executeScript` 向网页注入内容脚本
2. **数据读取**: 通过 `getLocalStorageItems()` 函数读取页面 localStorage
3. **数据写入**: 通过 `setLocalStorageItems()` 函数写入数据
4. **安全检查**: 使用 `isRestrictedUrl()` 检查受限 URL（如 `chrome://`, `file://`, `devtools://` 等）
5. **XSS 防护**: 所有用户输入通过 `escapeHtml()` 转义，防止跨站脚本攻击

## 🛠️ 开发与构建

### 前置要求

- Node.js 16+ 
- pnpm（推荐使用 pnpm 作为包管理器）

### 安装依赖

```bash
pnpm install
# 或使用 npm
npm install
```

### 编译 TypeScript

```bash
pnpm run build
# 或使用 npm
npm run build
```

编译后生成的文件位于 `dist/` 目录。

### 加载扩展到 Chrome

1. 打开 Chrome 浏览器，访问 `chrome://extensions/`
2. 右上角启用 **"开发者模式"**
3. 点击 **"加载已解压的扩展程序"**
4. 选择项目的根目录
5. 扩展图标将出现在浏览器工具栏中

## ⚠️ 安全特性

- **受限 URL 检测**: 自动阻止在 `chrome://`, `edge://`, `devtools://`, `file://`, `about:blank` 等特殊页面注入脚本
- **XSS 防护**: 所有 Toast 消息中的文本都会进行 HTML 转义，防止跨站脚本攻击
- **剪贴板回退方案**: 当现代 Clipboard API 不可用时，使用 `document.execCommand('copy')` 作为回退
- **JSON 格式验证**: 导入前严格验证 JSON 格式，确保数据安全
- **类型转换**: 自动将非字符串值转换为 JSON 字符串（localStorage 要求所有值为字符串）
- **自定义粘贴对话框**: 当剪贴板权限被拒绝时，提供友好的手动粘贴界面

## 📋 使用说明

### 场景一：开发环境迁移

假设你在本地开发环境（`http://localhost:3000`）调试好了一些配置，需要迁移到测试环境（`https://test.example.com`）：

1. **导出数据**
   - 打开 `http://localhost:3000`
   - 点击扩展图标
   - 点击 **"📤 导出当前网站数据"** 下载 JSON 文件

2. **导入数据**
   - 打开 `https://test.example.com`
   - 点击扩展图标
   - 点击 **"📥 导入数据到当前网站"**
   - 选择之前导出的 JSON 文件
   - 完成！

### 场景二：快速分享给同事

1. 点击 **"📋 复制到剪贴板"**
2. 将 JSON 数据发送给同事
3. 同事在其浏览器中点击 **"📋 从剪贴板粘贴"**
4. 数据自动导入

## 📝 注意事项

- **仅限普通网站使用**: 无法在浏览器内部页面（如 `chrome://`, `edge://` 等）使用
- **数据覆盖**: 导入操作会覆盖同名的现有键值，请谨慎操作
- **序列化限制**: localStorage 中的所有值都会被存储为字符串，复杂对象会自动序列化
- **文件大小**: 建议导出的 JSON 文件大小不超过 5MB（localStorage 容量限制）
- **隐私保护**: 请勿将包含敏感信息的导出数据分享给他人

## 🔍 常见问题

### Q: 为什么在某些页面无法使用？

A: 出于安全考虑，Chrome 扩展无法在浏览器内部页面（如 `chrome://`, `edge://`）、本地文件（`file://`）等受限页面注入脚本。

### Q: 导入后数据没有立即显示？

A: 部分网站可能需要刷新页面才会重新读取 localStorage。请尝试刷新页面查看最新数据。

### Q: 如何查看导出的数据内容？

A: 导出的 JSON 文件可以用任何文本编辑器打开查看和编辑。

## 📄 许可证

ISC License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个扩展！