Huggingface Spaces 部署检查清单

📋 必须上传的文件清单

✅ 核心文件

app.py - HF Spaces入口文件（已简化配置逻辑）
README.md - 带有正确YAML头的项目说明
requirements.txt - Python依赖
packages.txt - 系统依赖
config.toml - 配置文件

✅ 应用代码

app/ - 完整应用目录
webui/ - Streamlit界面
resource/ - 字体和音乐资源

✅ 文档文件

API_GUIDE.md - API使用指南
.gitignore - Git忽略文件

🚫 不需要上传的文件

❌ 开发文件

Dockerfile - HF不使用Docker构建
.dockerignore - HF不需要
docker-compose.yml - 本地开发用
main.py - 本地启动脚本
webui.bat / webui.sh - 本地脚本

❌ 示例和测试文件

config.example.toml - 示例配置
test/ - 测试目录
docs/ - 文档图片

🔧 API密钥配置优先级

配置方式选择

HF Spaces环境变量 (推荐) - 更安全，自动加载
WebUI界面配置 - 简单直观，适合测试

环境变量配置

在HF Spaces的Settings → Repository secrets中配置：

# 核心API密钥
MONEYPRINTER_API_KEY=your_api_key_here    # 用于外部API调用

# LLM服务（至少选择一个）
DEEPSEEK_API_KEY=your_deepseek_key        # 推荐
MOONSHOT_API_KEY=your_moonshot_key        # 推荐
OPENAI_API_KEY=your_openai_key

# 视频素材源（至少选择一个）
PEXELS_API_KEY=your_pexels_key            # 推荐
PIXABAY_API_KEY=your_pixabay_key

# 可选服务
AZURE_SPEECH_KEY=your_azure_key
AZURE_SPEECH_REGION=eastus

配置说明

环境变量会在启动时自动加载到config.toml
如果同时配置了环境变量和WebUI，环境变量优先
未配置环境变量时，可在WebUI中手动配置

🚀 使用方式

1. 仅WebUI使用

在左侧配置面板设置API密钥
通过界面生成视频

2. API调用

需要设置MONEYPRINTER_API_KEY环境变量
使用该密钥调用外部API接口
详见API_GUIDE.md

🔧 构建卡住的常见原因及解决方案

1. 缺少YAML头部

问题: README.md没有正确的YAML配置解决: 确保README.md开头有完整的YAML头部

2. 依赖版本冲突

问题: requirements.txt中的包版本不兼容解决: 使用优化后的requirements.txt（已修复）

3. 系统依赖缺失

问题: 缺少ffmpeg等系统依赖解决: 创建packages.txt文件（已创建）

4. 启动脚本问题

问题: app.py启动逻辑有误解决: 使用优化后的app.py（已修复）

5. 配置文件问题

问题: config.toml格式错误解决: 检查TOML语法，确保没有语法错误

🔍 部署后故障排除

检查构建日志

在HF Spaces界面查看"Logs"标签
寻找错误信息，通常出现在：
- 依赖安装阶段
- 应用启动阶段

常见错误及解决方案

错误: "No module named 'xxx'"

解决: 在requirements.txt中添加缺失的包

错误: "Address already in use"

解决: 检查app.py中的端口配置是否为7860

错误: "Permission denied"

解决: 检查文件权限，确保app.py有执行权限

错误: "ffmpeg not found"

解决: 确保packages.txt包含ffmpeg

📞 支持信息

如果部署仍然失败，请检查：

HF Spaces配额是否足够
是否选择了正确的SDK (Streamlit)
文件是否完整上传
YAML配置是否正确