Demo2APK 🚀

中文文档

将你的 Vibe Coding 创意瞬间转化为可运行的 Android 应用。

Demo2APK 是专为 Vibe Coding 用户打造的一键打包工具。无论你有一个精彩的演示项目，还是由 AI（Gemini、ChatGPT、DeepSeek 等）生成的完整项目，只需上传文件，我们便会立即为你生成一个可安装的 APK。无需复杂的 Android 开发环境配置——让创意触手可及。

请勿接受来自他人的 APK 文件，因为它们可能包含安全风险！

🌐 免费公共服务

我们为大家提供一个 免费公共实例：

👉 https://demo2apk.lasuo.ai

• 每个 IP 每小时最多可构建 5 次
• 无需注册
• 功能齐全，与自托管版本相同

希望这能帮到你！如果你觉得有用，请为本仓库点个 ⭐ 星吧！

✨ 核心功能

• 🎨 Web 界面: 沉浸式的“暗黑工程蓝图”风格 UI，用于管理构建任务。
• ✏️ 自定义: 支持在上传时设置自定义的 应用名称、应用版本（如 1.0.0）和 应用图标。
• 🔐 Android 权限: 可通过 UI 自定义 Android 权限——仅选择你的应用所需的权限（默认仅启用 INTERNET 权限）。
• 📱 PWA 支持: 可选地在生成 APK 的同时创建一个可安装的 渐进式 Web 应用，以便于 Web 部署。
• 📋 构建历史: 自动保存最近的构建记录，并支持页面刷新后的 会话恢复。
• 🧠 智能检测: 自动检测文件类型（HTML/React/ZIP），并选择最佳的构建策略。
• ⏳ 智能队列: 通过实时队列系统处理并发构建任务，并提供进度反馈。
• 🔗 轻松分享: 构建完成后，可立即生成可分享的下载链接。
• ⚡️ 极速响应: 经过优化的云流水线，可在数分钟内交付 APK。
• 🌐 灵活模式:
  • 单文件模式: 支持 .html、.js、.jsx、.ts、.tsx 文件（自动检测 React 组件）。
  • 粘贴代码模式: 直接粘贴代码，智能识别 HTML/React/JS 内容。
  • ZIP 压缩包模式: 支持标准的 React/Vite 项目（需执行 npm build）以及 多文件 HTML 项目（无需构建）。
• 🧠 智能离线处理: 自动处理 CDN 资源和 JSX 编译，确保你的应用在离线状态下也能流畅运行。
• 🛡️ 速率限制: 智能资源分配（开发模式下可配置）。
• 🧹 自动清理: 构建产物会在 2 小时后自动删除，以保护隐私并节省空间。

⚠️ React 项目：避免白屏问题

重要提示：如果你的 React/Vite APK 出现 白色或空白屏幕，你需要添加兼容 Android WebView 的 legacy 插件。

npm install -D @vitejs/plugin-legacy terser

// vite.config.js
import legacy from '@vitejs/plugin-legacy'

export default defineConfig({
  plugins: [
    react(),
    legacy({ targets: ['chrome >= 52', 'android >= 5'] })
  ],
  base: './'  // 对于 APK 必须设置！
})

📖 完整指南：React 项目要求 - 详细解决白屏问题的方法。

🚀 快速开始

选项 1：Docker 部署（Linux 服务器）

使用预构建的 Docker 镜像，3 分钟即可部署到你的 Linux 服务器上。

⚠️ Docker 镜像仅支持 linux/amd64。对于 macOS 用户，请使用 本地开发。

# 1. 创建部署目录
mkdir -p ~/demo2apk && cd ~/demo2apk

# 2. 下载部署配置文件
curl -O https://raw.githubusercontent.com/DeadWaveWave/demo2apk/main/docker-compose.deploy.yml

# 3. （可选）配置环境变量
curl -O https://raw.githubusercontent.com/DeadWaveWave/demo2apk/main/.env.deploy.example
mv .env.deploy.example .env
# 编辑 .env 文件以自定义设置（速率限制、PWA、资源限制等）

# 4. 启动服务
docker compose -f docker-compose.deploy.yml up -d

访问 http://127.0.0.1:5173 即可使用 Web UI。

更新到最新版本：

docker compose -f docker-compose.deploy.yml pull && docker compose -f docker-compose.deploy.yml up -d

选项 2：本地开发（macOS / Linux）

适用于 macOS 用户或本地开发：

# 1. 安装依赖
pnpm install

# 2. 启动 Redis
docker run -d -p 6379:6379 redis:alpine

# 3. 构建项目
pnpm build

# 4. 启动所有服务（分别在不同终端中）
pnpm dev        # API 服务器（端口 3000）
pnpm worker     # 构建工作进程
pnpm frontend   # Web UI（端口 5173）

访问 http://localhost:5173 即可使用 Web UI。

选项 2：API 使用

如果你更倾向于命令行或脚本集成，可以使用我们的 REST API。

单个 HTML 文件：

curl -X POST http://localhost:3000/api/build/html \
  -F "file=@test-demo.html" \
  -F "appName=TestDemo"

React 项目：

# 先将项目打包成 ZIP 文件
zip -r test-react-app.zip test-react-app/

# 上传并构建（自动检测项目类型）
curl -X POST http://localhost:3000/api/build/zip \
  -F "file=@test-react-app.zip" \
  -F "appName=TestReactApp"

粘贴代码：

# 上传原始代码（HTML/JS/React）
curl -X POST http://localhost:3000/api/build/code \
  -F "code=<export default function App() { return <h1>Hello</h1> }" \
  -F "appName=MyReactApp"

详情请参阅 API 文档。

⚙️ 配置

速率限制

为确保公平使用，默认启用了速率限制：

• 限制：每个 IP 每小时最多 5 次请求。
• 开发模式：可通过环境变量禁用，用于本地开发。

在 .env 中设置：

# 禁用速率限制（仅限开发/测试）
RATE_LIMIT_ENABLED=false

# 自定义限制（默认 5 次）
RATE_LIMIT_MAX=10

文件保留

为节省存储空间并保护用户数据：

• 保留期限：生成的 APK 和临时文件将在 2 小时 后被删除。
• 清理机制：后台工作进程每 30 分钟扫描一次过期文件（可配置）。

可通过环境变量进行配置：

# 保留期限（小时）
FILE_RETENTION_HOURS=2

# 是否在每次构建后删除 Cordova/Capacitor 工作目录
CLEANUP_BUILD_ARTIFACTS=true

# 是否在每次任务完成后删除上传的文件（默认 true）
CLEANUP_UPLOADS_ON_COMPLETE=true

# 工作进程侧清理旧 APK/构建/上传文件
FILE_CLEANUP_ENABLED=true
FILE_CLEANUP_INTERVAL_MINUTES=30

并发与队列

控制同时运行的构建任务数量。超出数量的任务将自动进入队列。

# 并发构建任务数（默认 2 个）
WORKER_CONCURRENCY=2

📝 更改日志

发布历史请参阅 CHANGELOG.md。

📚 文档

• API 文档 - 完整的 REST API 参考
• 部署指南 - 生产环境部署说明
• React 项目指南 - 保证 React 兼容性的最佳实践（避免出现空白屏幕）

🛠️ 技术栈

• 前端: React、Vite、Tailwind CSS（Blueprint 风格）
• 后端: Node.js、Fastify、TypeScript
• 队列: BullMQ、Redis
• 构建: Cordova、Capacitor、Gradle
• 部署: Docker、Docker Compose

📈 社区

---

为 Vibe Coding 而用心打造

Demo2APK 快速上手指南

Demo2APK 是一款专为"Vibe Coding"用户打造的一键打包工具。它能将 AI 生成的演示项目（HTML/React/Vite 等）瞬间转换为可安装的 Android APK 文件，无需配置复杂的 Android 开发环境。

环境准备

在部署前，请确保您的系统满足以下要求：

• 操作系统：
  • Linux (推荐)：支持 linux/amd64 架构，适用于生产环境 Docker 部署。
  • macOS / Linux：适用于本地开发调试。
  • 注意：Docker 镜像暂不支持 macOS 直接运行，Mac 用户请使用“本地开发”模式。
• 前置依赖：
  • Docker & Docker Compose：用于快速部署服务（生产环境必需）。
  • Node.js & pnpm：用于本地源码运行和开发。
  • Redis：用于任务队列管理（本地开发需单独启动）。

安装步骤

您可以根据使用场景选择以下两种安装方式之一：

方案一：Docker 部署（推荐 Linux 服务器）

此方案适合快速搭建生产环境，全程约需 3 分钟。

# 1. 创建部署目录并进入
mkdir -p ~/demo2apk && cd ~/demo2apk

# 2. 下载 Docker Compose 配置文件
curl -O https://raw.githubusercontent.com/DeadWaveWave/demo2apk/main/docker-compose.deploy.yml

# 3. (可选) 下载并配置环境变量
# 如需自定义限流、PWA 设置等，可编辑 .env 文件
curl -O https://raw.githubusercontent.com/DeadWaveWave/demo2apk/main/.env.deploy.example
mv .env.deploy.example .env

# 4. 启动服务
docker compose -f docker-compose.deploy.yml up -d

启动完成后，访问 http://127.0.0.1:5173 即可使用 Web 界面。

方案二：本地开发部署（macOS / Linux）

此方案适合开发者进行源码调试或二次开发。

# 1. 安装项目依赖
pnpm install

# 2. 启动 Redis 服务 (需已安装 Docker)
docker run -d -p 6379:6379 redis:alpine

# 3. 构建项目
pnpm build

# 4. 分别在不同终端窗口启动以下三个服务
pnpm dev        # 启动 API 服务器 (端口 3000)
pnpm worker     # 启动构建工作器
pnpm frontend   # 启动 Web 前端界面 (端口 5173)

启动完成后，访问 http://localhost:5173 即可使用。

基本使用

安装完成后，您可以通过 Web 界面 或 API 命令行 两种方式生成 APK。

方式 A：Web 界面操作（最简单）

1. 浏览器访问部署地址（如 http://localhost:5173）。
2. 上传您的代码文件：
   • 单文件模式：直接上传 .html, .js, .jsx 等文件。
   • 项目模式：上传包含 package.json 的 React/Vite 项目 ZIP 包。
   • 代码粘贴：直接将代码粘贴到输入框。
3. （可选）自定义应用名称、版本号、图标及权限。
4. 点击构建，等待完成后下载 APK 或分享链接。

方式 B：API 命令行调用

如果您希望通过脚本自动化构建，可使用以下 curl 命令示例：

1. 构建单个 HTML 文件：

curl -X POST http://localhost:3000/api/build/html \
  -F "file=@test-demo.html" \
  -F "appName=TestDemo"

2. 构建 React/Vite 项目（需先打包为 ZIP）：

# 先将项目压缩
zip -r test-react-app.zip test-react-app/

# 上传并构建（自动识别项目类型）
curl -X POST http://localhost:3000/api/build/zip \
  -F "file=@test-react-app.zip" \
  -F "appName=TestReactApp"

3. 直接粘贴代码构建：

curl -X POST http://localhost:3000/api/build/code \
  -F "code=<export default function App() { return <h1>Hello</h1> }>" \
  -F "appName=MyReactApp"

💡 重要提示（React 项目白屏问题） 如果您的 React/Vite 项目生成的 APK 出现白屏，请在项目中安装兼容插件并修改 vite.config.js：

npm install -D @vitejs/plugin-legacy terser

// vite.config.js
import legacy from '@vitejs/plugin-legacy'

export default defineConfig({
  plugins: [
    react(),
    legacy({ targets: ['chrome >= 52', 'android >= 5'] })
  ],
  base: './'  // 必须设置为相对路径
})