You've already forked Nano-Banana-AI-Image-Editor
230 lines
8.3 KiB
Markdown
230 lines
8.3 KiB
Markdown
# 🍌 Nano Banana AI 图像编辑器
|
||
|
||
发布版本: v1.0
|
||
|
||
### **⏬ 获取一键安装副本!**
|
||
加入 [Vibe Coding is Life Skool 社区](https://www.skool.com/vibe-coding-is-life/about?ref=456537abaf37491cbcc6976f3c26af41) 获取此应用的 **一键 ⚡Bolt.new 安装克隆**，以及现场构建会话、独家项目下载、AI 提示、大师课程和网络上最好的氛围编码社区的访问权限！
|
||
|
||
---
|
||
|
||
**专业的 AI 图像生成和对话式编辑平台**
|
||
|
||
一个生产就绪的 React + TypeScript 应用程序，用于愉快的图像生成和使用 Google Gemini 2.5 Flash Image 模型进行对话式、区域感知的修改。采用现代网络技术构建，专为创作者和开发者设计。
|
||
|
||
## ✨ 主要功能
|
||
|
||
### 🎨 **AI 驱动的创作**
|
||
- **文本到图像生成** - 从描述性提示创建令人惊叹的图像
|
||
- **实时质量提示** - 实时反馈以改进您的提示
|
||
- **参考图像支持** - 使用最多 2 张参考图像指导生成
|
||
- **高级控制** - 微调创意水平并使用自定义种子
|
||
|
||
### ✏️ **智能编辑**
|
||
- **对话式编辑** - 使用自然语言指令修改图像
|
||
- **区域感知选择** - 绘制遮罩以针对特定区域进行编辑
|
||
- **样式参考图像** - 上传参考图像以指导编辑样式
|
||
- **非破坏性工作流** - 所有编辑都保留原始图像
|
||
|
||
### 🖼️ **专业画布**
|
||
- **交互式画布** - 平滑缩放、平移和导航大图像
|
||
- **画笔工具** - 可变画笔尺寸以实现精确的遮罩绘制
|
||
- **移动设备优化** - 响应式设计，在所有设备上都能完美运行
|
||
- **键盘快捷键** - 使用热键提高工作效率
|
||
|
||
### 📚 **项目管理**
|
||
- **生成历史** - 跟踪所有创作和编辑
|
||
- **变体比较** - 生成并并排比较多个版本
|
||
- **完整撤销/重做** - 具有分支历史的完整生成树
|
||
- **资产管理** - 有序存储所有生成的内容
|
||
|
||
### 🔒 **企业功能**
|
||
- **图像上传和分享** - 上传生成的图像以轻松分享
|
||
- **离线缓存** - IndexedDB 存储以实现离线资产访问
|
||
- **类型安全** - 完整的 TypeScript 实现和严格类型检查
|
||
- **性能优化** - React Query 实现高效状态管理
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 先决条件
|
||
- Node.js 18+
|
||
- 一个 [Google AI Studio](https://aistudio.google.com/) API 密钥
|
||
- 可选：访问令牌用于图像上传功能
|
||
|
||
### 安装
|
||
|
||
1. **克隆并安装依赖**:
|
||
```bash
|
||
git clone <repository-url>
|
||
cd nano-banana-image-editor
|
||
npm install
|
||
```
|
||
|
||
2. **配置环境**:
|
||
```bash
|
||
cp .env.example .env
|
||
# 将您的 Gemini API 密钥添加到 VITE_GEMINI_API_KEY
|
||
# 可选：添加访问令牌到 VITE_ACCESS_TOKEN 以启用图像上传
|
||
```
|
||
|
||
3. **启动开发服务器**:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
4. **在浏览器中打开**: 导航到 `http://localhost:5173`
|
||
|
||
## 🎯 使用指南
|
||
|
||
### 创建图像
|
||
1. 选择 **生成** 模式
|
||
2. 编写详细提示描述您想要的图像
|
||
3. 可选上传参考图像（最多 2 张）
|
||
4. 如需要调整创意设置
|
||
5. 点击 **生成** 或按 `Cmd/Ctrl + Enter`
|
||
|
||
### 编辑图像
|
||
1. 切换到 **编辑** 模式
|
||
2. 上传图像或使用先前生成的图像
|
||
3. 可选绘制遮罩以针对特定区域
|
||
4. 用自然语言描述您想要的更改
|
||
5. 点击 **应用编辑** 查看结果
|
||
|
||
### 高级工作流
|
||
- 使用 **选择** 模式绘制精确遮罩以进行目标编辑
|
||
- 在历史面板中比较变体
|
||
- 下载高质量 PNG 输出
|
||
- 使用键盘快捷键进行高效导航
|
||
|
||
## ⌨️ 键盘快捷键
|
||
|
||
| 快捷键 | 操作 |
|
||
|----------|--------|
|
||
| `Cmd/Ctrl + Enter` | 生成/应用编辑 |
|
||
| `Enter` | 生成/应用编辑（在任何地方按下）|
|
||
| `Shift + R` | 重新生成变体 |
|
||
| `E` | 切换到编辑模式 |
|
||
| `G` | 切换到生成模式 |
|
||
| `M` | 切换到选择模式 |
|
||
| `H` | 切换历史面板 |
|
||
| `P` | 切换提示面板 |
|
||
| `Esc` | 中断生成 |
|
||
|
||
## 🏗️ 架构
|
||
|
||
### 技术栈
|
||
- **前端**: React 18, TypeScript, Tailwind CSS
|
||
- **状态管理**: Zustand 用于应用状态, React Query 用于服务器状态
|
||
- **画布**: Konva.js 用于交互式图像显示和遮罩叠加
|
||
- **AI 集成**: Google Generative AI SDK (Gemini 2.5 Flash Image)
|
||
- **存储**: IndexedDB 用于离线资产缓存
|
||
- **构建工具**: Vite 用于快速开发和优化构建
|
||
|
||
### 项目结构
|
||
```
|
||
src/
|
||
├── components/ # React 组件
|
||
│ ├── ui/ # 可重用的 UI 组件 (Button, Input, 等)
|
||
│ ├── PromptComposer.tsx # 提示输入和工具选择
|
||
│ ├── ImageCanvas.tsx # 使用 Konva 的交互式画布
|
||
│ ├── HistoryPanel.tsx # 生成历史和变体
|
||
│ ├── Header.tsx # 应用头部和导航
|
||
│ └── InfoModal.tsx # 关于模态框和链接
|
||
├── services/ # 外部服务集成
|
||
│ ├── geminiService.ts # Gemini API 客户端
|
||
│ ├── uploadService.ts # 图像上传服务
|
||
│ ├── cacheService.ts # IndexedDB 缓存层
|
||
│ └── imageProcessing.ts # 图像处理工具
|
||
├── store/ # Zustand 状态管理
|
||
│ └── useAppStore.ts # 全局应用状态
|
||
├── hooks/ # 自定义 React 钩子
|
||
│ ├── useImageGeneration.ts # 生成和编辑逻辑
|
||
│ └── useKeyboardShortcuts.ts # 键盘导航
|
||
├── utils/ # 工具函数
|
||
│ ├── cn.ts # 类名工具
|
||
│ └── imageUtils.ts # 图像处理助手
|
||
└── types/ # TypeScript 类型定义
|
||
└── index.ts # 核心类型定义
|
||
```
|
||
|
||
## 🔧 配置
|
||
|
||
### 环境变量
|
||
```bash
|
||
VITE_GEMINI_API_KEY=your_gemini_api_key_here
|
||
VITE_ACCESS_TOKEN=your_access_token_here # 可选，用于图像上传
|
||
VITE_UPLOAD_ASSET_URL=your_asset_url # 可选，用于图像上传的资产URL前缀
|
||
```
|
||
|
||
### 模型配置
|
||
- **模型**: `gemini-2.5-flash-image-preview`
|
||
- **输出格式**: 1024×1024 PNG
|
||
- **输入格式**: PNG, JPEG, WebP
|
||
- **温度范围**: 0-1 (0 = 确定性, 1 = 创意)
|
||
|
||
## 🚀 部署
|
||
|
||
### 开发
|
||
```bash
|
||
npm run dev # 启动开发服务器
|
||
npm run build # 构建生产版本
|
||
npm run preview # 预览生产构建
|
||
npm run lint # 运行 ESLint
|
||
```
|
||
|
||
### 生产考虑
|
||
- **API 安全**: 在生产环境中为 API 调用实现后端代理
|
||
- **速率限制**: 添加适当的速率限制和使用配额
|
||
- **身份验证**: 考虑为多用户部署添加用户身份验证
|
||
- **存储**: 设置云存储以存储生成的资产
|
||
- **监控**: 添加错误跟踪和分析
|
||
|
||
## 📄 许可证和版权
|
||
|
||
**版权所有 © 2025 [Mark Fulton](https://markfulton.com)**
|
||
|
||
该项目根据 **GNU Affero 通用公共许可证 v3.0** (AGPL-3.0) 授权。
|
||
|
||
### 这意味着：
|
||
- ✅ **免费使用** 于个人和商业项目
|
||
- ✅ **修改和分发** 需要适当署名
|
||
- ⚠️ **分享修改** - 任何更改必须在相同许可证下共享
|
||
- ⚠️ **网络使用** - 如果您将其作为网络服务运行，必须提供源代码
|
||
|
||
有关完整详情，请参见 [LICENSE](LICENSE) 文件。
|
||
|
||
## 🤝 贡献
|
||
|
||
我们欢迎贡献！请：
|
||
|
||
1. **遵循既定模式** - 保持组件在 200 行以内
|
||
2. **维护类型安全** - 严格使用 TypeScript 和正确定义
|
||
3. **彻底测试** - 确保键盘导航和可访问性
|
||
4. **记录更改** - 更新 README 并添加内联注释
|
||
5. **遵守许可证** - 所有贡献都将遵循 AGPL-3.0
|
||
|
||
## 🔗 链接和资源
|
||
|
||
- **创建者**: [Mark Fulton](https://markfulton.com)
|
||
- **AI 培训计划**: [Reinventing.AI](https://www.reinventing.ai/)
|
||
- **社区**: [Vibe Coding is Life Skool](https://www.skool.com/vibe-coding-is-life/about?ref=456537abaf37491cbcc6976f3c26af41)
|
||
- **Google AI Studio**: [获取您的 API 密钥](https://aistudio.google.com/)
|
||
- **Gemini API 文档**: [官方文档](https://ai.google.dev/gemini-api/docs)
|
||
|
||
## 🐛 已知问题和限制
|
||
|
||
- **客户端 API 调用** - 目前使用直接 API 调用（在生产环境中实现后端代理）
|
||
- **浏览器兼容性** - 需要支持 Canvas 和 WebGL 的现代浏览器
|
||
- **速率限制** - 受 Google AI Studio 速率限制约束
|
||
- **图像尺寸** - 针对 1024×1024 输出进行了优化（Gemini 模型输出尺寸可能有所不同）
|
||
|
||
## 🎯 建议更新
|
||
|
||
- [ ] 后端 API 代理实现
|
||
- [ ] 用户身份验证和项目共享
|
||
- [ ] 高级画笔工具和选择方法
|
||
- [ ] 自定义过滤器的插件系统
|
||
- [ ] 与云存储提供商集成
|
||
|
||
---
|
||
|
||
**由 [Mark Fulton](https://markfulton.com) 构建** | **由 Gemini 2.5 Flash Image 提供支持** | **使用 Bolt.new 制作** |