diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b2e369e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+# S3 数据迁移工具
+
+一个简单高效的 S3 对象存储迁移工具，支持在不同 S3 兼容存储服务之间迁移数据。
+
+## 功能特性
+
+- **智能对比**：通过 ETag 对比文件差异，避免重复传输
+- **断点续传**：支持中断后继续迁移，已存在的文件会自动跳过
+- **增量同步**：只迁移变化或新增的文件
+- **详细日志**：清晰的进度显示和结果统计
+
+## 支持的存储服务
+
+- Amazon S3
+- MinIO
+- 阿里云 OSS
+- 腾讯云 COS
+- 火山引擎 TOS
+- 其他 S3 兼容的存储服务
+
+## 环境配置
+
+创建 `.env` 文件，配置源存储和目标存储信息：
+
+```bash
+# 源存储配置（旧 S3）
+O_S3_ACCESS_KEY_ID=your_access_key
+O_S3_SECRET_ACCESS_KEY=your_secret_key
+O_S3_REGION=us-east-1
+O_S3_BUCKET_NAME=source-bucket
+O_S3_ENDPOINT=http://localhost:9000
+
+# 目标存储配置（新 S3）
+S3_ACCESS_KEY_ID=your_access_key
+S3_SECRET_ACCESS_KEY=your_secret_key
+S3_REGION=cn-shanghai
+S3_BUCKET_NAME=destination-bucket
+S3_ENDPOINT=https://tos-s3-cn-shanghai.volces.com
+```
+
+参考 `.env.example` 文件获取完整配置示例。
+
+### 注意事项
+
+**MinIO 用户**：如果使用 MinIO 作为源存储，需要在代码中设置 `forcePathStyle: true`。默认配置已包含此设置，无需修改。
+
+```typescript
+const oldS3Client = new S3Client({
+  // ...
+  forcePathStyle: true,  // MinIO 必需
+});
+```
+
+## 安装
+
+```bash
+# 安装依赖
+pnpm install
+```
+
+## 使用方法
+
+```bash
+# 运行迁移
+pnpm migrate
+```
+
+## 运行逻辑
+
+对于每个文件，迁移脚本会执行以下操作：
+
+| 状态 | 操作 |
+|------|------|
+| 目标不存在 | 复制文件（新增） |
+| 目标存在，ETag 不同 | 更新文件 |
+| 目标存在，ETag 相同 | 跳过 |
+
+## 输出示例
+
+```
+Starting S3 migration...
+Source: http://kevisual.cn:9000/resources
+Destination: https://tos-s3-cn-shanghai.volces.com/envision
+
+Found 10 objects in source bucket
+Copying: images/photo1.jpg
+✓ Copied: images/photo1.jpg
+- Skip (same ETag): images/photo2.jpg
+Updating (ETag changed): documents/report.pdf
+  Source ETag: abc123def456
+  Dest ETag:   789xyz012abc
+✓ Copied: documents/report.pdf
+
+Migration complete!
+Total objects: 10
+Copied (new): 2
+Updated (ETag changed): 1
+Skipped (same): 7
+Errors: 0
+```
+
+## 技术栈
+
+- **TypeScript** - 类型安全
+- **AWS SDK v3** - S3 客户端
+- **dotenv** - 环境变量管理
+
+## License
+
+ISC