Better-Douyin 详细部署教程

Better-Douyin 是一款第三方抖音桌面工具，基于 Rust 和 Tauri 构建，旨在提供更轻量、更流畅的桌面浏览和下载体验。它支持作者级内容下载、私信、通知、AI 互动等功能。请注意，本项目开源部分仅为 UI 展示壳 (Open Shell)，完整功能需从 Releases 页面下载。

本教程将引导你了解项目结构、安装完整应用，以及从源码运行演示界面。

1. 项目重要说明

在开始前，请务必理解 Better-Douyin 的发布模式：

完整应用 (完整功能)：在项目的 Releases 页面提供下载。普通用户应直接下载此版本，无需从源码构建。
公开源码 (Open Shell)：当前 GitHub 仓库的源码是“公开壳子”，主要用于展示 UI 和前端架构，不包含任何真实的平台连接器、签名、Cookie、加密或下载解析逻辑。
许可协议：本项目采用 Better Douyin Non-Commercial License，仅允许个人非商业（学习、研究、测试）使用。禁止任何形式的商业分发、收费下载或营利性使用。

⚠️ 重要免责：使用者应遵守平台规则，自行承担因使用方式、请求频率、平台策略变化导致的账号异常、限流、封禁等风险。作者不提供规避风控或解封的支持。

2. 安装完整应用 (推荐)

2.1 下载与校验

访问项目的 Releases 页面。
下载适用于你操作系统的最新安装包（如 .dmg、.exe、.AppImage）。
强烈建议校验文件完整性：下载页面同时提供 checksums.sha256 或 checksums.json 文件。使用工具核对下载文件的 SHA-256 哈希值，确保未被篡改。

2.2 安装与启动

macOS：打开下载的 .dmg 文件，将应用拖入 Applications 文件夹。
Windows：运行下载的 .exe 安装程序，按向导完成安装。
Linux：运行下载的 .AppImage 文件（可能需要先赋予执行权限：chmod +x *.AppImage）。

启动应用后，你即可使用其完整功能，包括内容获取、下载管理、播放互动、AI 助手等。

3. 从源码运行 UI 演示 (开发者)

如果你是一位开发者，希望改进 UI、主题或组件，可以按照以下步骤在本地运行公开的 UI 演示壳。

3.1 准备工作

Node.js 环境 (推荐最新 LTS 版本)
npm 包管理器

3.2 克隆仓库与安装依赖

1
2
3

git clone https://github.com/anYuJia/better-douyin.git
cd better-douyin
npm --prefix frontend install

3.3 启动开发服务器

1	npm run dev

此命令会启动前端开发服务器，默认在 http://localhost:5173 或类似地址打开一个 UI 演示页面。该演示使用 Mock 数据，展示界面交互，但不会访问真实平台。

3.4 构建与预览生产版本

如果你想构建静态文件并预览：

1 2	npm run build # 构建前端 npm run server # 启动一个本地静态服务器预览 dist/ 目录

3.5 一条命令运行完整演示

1	npm run demo

此命令会依次执行构建并启动预览服务器。

4. 项目结构与二次开发要点

4.1 关键目录

.
├── frontend/          # React + TypeScript UI 主目录
│   ├── src/           # 页面、组件、状态管理 (Zustand)、Hooks、类型
│   └── public/        # 静态资源
├── backend/
│   └── server.mjs     # 安全的 Node.js Mock 后端 (仅返回演示数据)
└── docs/              # 文档，如适配器边界说明

4.2 给贡献者和 AI 协作者的边界说明

可接受贡献：UI/UX 改进、组件拆分、主题调整、Mock 数据优化、文档完善。
明确不接受：任何涉及真实接口、签名、Cookie、加密、风控绕过、逆向工程或批量请求的代码。
在开始贡献前，请务必阅读项目中的 SECURITY_BOUNDARY.md 和 docs/adapter-boundary.md 文件，了解公开源码的安全边界。

5. 故障排除

问题	可能原因与解决方案
下载的完整应用无法启动或提示损坏 (macOS)	macOS 可能阻止未签名应用。尝试在“系统设置” > “隐私与安全性”中点击“仍要打开”。或使用命令行：`xattr -cr /Applications/Better-Douyin.app`。
从源码运行 `npm run dev` 后只看到空白页	检查控制台是否有错误。确保 Node.js 版本兼容。尝试删除 `node_modules` 并重新 `npm install`。
UI 演示中的功能无法真实下载	这是预期行为。公开源码仅包含 Mock 演示，完整下载功能仅在 Releases 的完整应用中提供。
如何获取真实平台支持？	完整功能请从 Releases 页面下载官方发行版。公开源码不包含也不接受真实平台连接的贡献。