docs：添加完整的项目文档体系
- 添加Web部署完整指南和更新日志 - 创建网络管理器配置文档 - 完善项目设置和测试指南 - 添加API更新日志和清理总结 - 更新脚本使用说明文档
This commit is contained in:
553
docs/web_deployment_guide.md
Normal file
553
docs/web_deployment_guide.md
Normal file
@@ -0,0 +1,553 @@
|
||||
# Web部署完整指南
|
||||
|
||||
**版本**: 1.0.0
|
||||
**更新时间**: 2025-12-25
|
||||
**适用于**: Godot 4.5+ 项目
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [导出准备](#导出准备)
|
||||
2. [Godot编辑器配置](#godot编辑器配置)
|
||||
3. [自动化导出脚本](#自动化导出脚本)
|
||||
4. [本地测试](#本地测试)
|
||||
5. [生产环境部署](#生产环境部署)
|
||||
6. [服务器配置](#服务器配置)
|
||||
7. [性能优化](#性能优化)
|
||||
8. [常见问题解决](#常见问题解决)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 导出准备
|
||||
|
||||
### 系统要求
|
||||
- Godot 4.5+
|
||||
- Python 3.x（用于本地测试服务器）
|
||||
- Web服务器（Apache/Nginx/IIS等）
|
||||
|
||||
### 项目结构检查
|
||||
确保项目结构完整：
|
||||
```
|
||||
whaleTown/
|
||||
├── assets/ # 游戏资源
|
||||
├── core/ # 核心系统
|
||||
├── scenes/ # 场景文件
|
||||
├── scripts/ # 脚本文件
|
||||
├── docs/ # 文档
|
||||
├── build/ # 导出目录（自动创建）
|
||||
└── project.godot # 项目配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Godot编辑器配置
|
||||
|
||||
### 1. 下载导出模板
|
||||
1. 打开Godot编辑器
|
||||
2. 点击 `Project` → `Export...`
|
||||
3. 点击 `Manage Export Templates...`
|
||||
4. 点击 `Download and Install` 下载Godot 4.5导出模板
|
||||
5. 等待下载完成
|
||||
|
||||
### 2. 创建Web导出预设
|
||||
1. 在Export窗口中点击 `Add...`
|
||||
2. 选择 `Web` 平台
|
||||
3. 配置以下设置：
|
||||
|
||||
#### 基本设置
|
||||
```
|
||||
Name: Web
|
||||
Export Path: build/web/index.html
|
||||
Runnable: ✓ 启用
|
||||
Dedicated Server: ✗ 禁用
|
||||
```
|
||||
|
||||
#### Web选项
|
||||
```
|
||||
Variant: release
|
||||
Vram Texture Compression: ✓ 启用
|
||||
Export Type: Regular
|
||||
Custom HTML Shell: res://assets/web/custom_shell.html
|
||||
Head Include: (留空，已在自定义模板中配置)
|
||||
```
|
||||
|
||||
#### 高级选项
|
||||
```
|
||||
Custom HTML Shell: res://assets/web/custom_shell.html
|
||||
Progressive Web App: ✓ 启用（可选）
|
||||
Icon 144x144: res://icon.svg
|
||||
Icon 180x180: res://icon.svg
|
||||
Icon 512x512: res://icon.svg
|
||||
```
|
||||
|
||||
### 3. 项目设置优化
|
||||
在 `Project Settings` 中配置：
|
||||
|
||||
#### 渲染设置
|
||||
```
|
||||
Rendering > Renderer:
|
||||
- Rendering Method: gl_compatibility
|
||||
- Rendering Method Mobile: gl_compatibility
|
||||
|
||||
Rendering > Textures:
|
||||
- VRAM Compression > Import ETC2 ASTC: ✓
|
||||
```
|
||||
|
||||
#### 网络设置
|
||||
```
|
||||
Network > SSL:
|
||||
- Certificates Bundle: (如果需要HTTPS API调用)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 自动化导出脚本
|
||||
|
||||
### Windows批处理脚本
|
||||
|
||||
创建 `scripts/build_web.bat`：
|
||||
```batch
|
||||
@echo off
|
||||
setlocal enabledelayedexpansion
|
||||
|
||||
echo ========================================
|
||||
echo 鲸鱼镇 Web版本导出工具
|
||||
echo ========================================
|
||||
echo.
|
||||
|
||||
REM 配置变量
|
||||
set "PROJECT_NAME=whaleTown"
|
||||
set "BUILD_DIR=build\web"
|
||||
set "GODOT_PATH=C:\Program Files\Godot\Godot.exe"
|
||||
set "EXPORT_PRESET=Web"
|
||||
|
||||
REM 检查Godot是否存在
|
||||
if not exist "%GODOT_PATH%" (
|
||||
echo [错误] 未找到Godot可执行文件: %GODOT_PATH%
|
||||
echo 请修改脚本中的GODOT_PATH变量
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
REM 创建构建目录
|
||||
echo [信息] 创建构建目录...
|
||||
if not exist "build" mkdir "build"
|
||||
if not exist "%BUILD_DIR%" mkdir "%BUILD_DIR%"
|
||||
|
||||
REM 清理旧文件
|
||||
echo [信息] 清理旧的导出文件...
|
||||
if exist "%BUILD_DIR%\*" del /q "%BUILD_DIR%\*"
|
||||
|
||||
REM 导出项目
|
||||
echo [信息] 开始导出Web版本...
|
||||
echo 导出路径: %BUILD_DIR%\index.html
|
||||
echo.
|
||||
|
||||
"%GODOT_PATH%" --headless --export-release "%EXPORT_PRESET%" "%BUILD_DIR%\index.html"
|
||||
|
||||
if %ERRORLEVEL% neq 0 (
|
||||
echo [错误] 导出失败！错误代码: %ERRORLEVEL%
|
||||
pause
|
||||
exit /b %ERRORLEVEL%
|
||||
)
|
||||
|
||||
REM 复制额外文件
|
||||
echo [信息] 复制配置文件...
|
||||
copy "web\*.json" "%BUILD_DIR%\" >nul 2>&1
|
||||
copy "web\*.ico" "%BUILD_DIR%\" >nul 2>&1
|
||||
|
||||
REM 生成部署信息
|
||||
echo [信息] 生成部署信息...
|
||||
echo {> "%BUILD_DIR%\deploy_info.json"
|
||||
echo "project": "%PROJECT_NAME%",>> "%BUILD_DIR%\deploy_info.json"
|
||||
echo "version": "1.0.0",>> "%BUILD_DIR%\deploy_info.json"
|
||||
echo "build_time": "%date% %time%",>> "%BUILD_DIR%\deploy_info.json"
|
||||
echo "platform": "web">> "%BUILD_DIR%\deploy_info.json"
|
||||
echo }>> "%BUILD_DIR%\deploy_info.json"
|
||||
|
||||
echo.
|
||||
echo ========================================
|
||||
echo 导出完成！
|
||||
echo ========================================
|
||||
echo 导出位置: %BUILD_DIR%\
|
||||
echo 文件大小:
|
||||
for %%f in ("%BUILD_DIR%\*") do echo %%~nxf: %%~zf bytes
|
||||
|
||||
echo.
|
||||
echo 下一步:
|
||||
echo 1. 运行 scripts\serve_web.bat 进行本地测试
|
||||
echo 2. 将 %BUILD_DIR%\ 目录上传到Web服务器
|
||||
echo.
|
||||
pause
|
||||
```
|
||||
|
||||
### 本地测试服务器脚本
|
||||
|
||||
创建 `scripts/serve_web.bat`：
|
||||
```batch
|
||||
@echo off
|
||||
setlocal enabledelayedexpansion
|
||||
|
||||
echo ========================================
|
||||
echo 鲸鱼镇 本地Web服务器
|
||||
echo ========================================
|
||||
echo.
|
||||
|
||||
set "BUILD_DIR=build\web"
|
||||
set "PORT=8000"
|
||||
|
||||
REM 检查导出文件
|
||||
if not exist "%BUILD_DIR%\index.html" (
|
||||
echo [错误] 未找到Web导出文件！
|
||||
echo 请先运行 scripts\build_web.bat 导出项目
|
||||
echo.
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
REM 检查Python
|
||||
python --version >nul 2>&1
|
||||
if %ERRORLEVEL% neq 0 (
|
||||
echo [错误] 未找到Python！
|
||||
echo 请安装Python 3.x: https://python.org
|
||||
echo.
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
REM 显示文件信息
|
||||
echo [信息] Web文件信息:
|
||||
for %%f in ("%BUILD_DIR%\*") do (
|
||||
set "size=%%~zf"
|
||||
set /a "size_mb=!size!/1024/1024"
|
||||
echo %%~nxf: !size_mb! MB
|
||||
)
|
||||
|
||||
echo.
|
||||
echo [信息] 启动本地服务器...
|
||||
echo 端口: %PORT%
|
||||
echo 目录: %BUILD_DIR%
|
||||
echo.
|
||||
echo ========================================
|
||||
echo 在浏览器中访问: http://localhost:%PORT%
|
||||
echo 按 Ctrl+C 停止服务器
|
||||
echo ========================================
|
||||
echo.
|
||||
|
||||
REM 切换到构建目录并启动服务器
|
||||
cd "%BUILD_DIR%"
|
||||
python -m http.server %PORT%
|
||||
|
||||
echo.
|
||||
echo 服务器已停止
|
||||
pause
|
||||
```
|
||||
|
||||
### Linux/macOS脚本
|
||||
|
||||
创建 `scripts/build_web.sh`：
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
echo "========================================"
|
||||
echo " 鲸鱼镇 Web版本导出工具"
|
||||
echo "========================================"
|
||||
echo
|
||||
|
||||
# 配置变量
|
||||
PROJECT_NAME="whaleTown"
|
||||
BUILD_DIR="build/web"
|
||||
GODOT_PATH="/usr/local/bin/godot" # 根据实际安装路径修改
|
||||
EXPORT_PRESET="Web"
|
||||
|
||||
# 检查Godot
|
||||
if [ ! -f "$GODOT_PATH" ]; then
|
||||
echo "[错误] 未找到Godot: $GODOT_PATH"
|
||||
echo "请修改脚本中的GODOT_PATH变量"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 创建构建目录
|
||||
echo "[信息] 创建构建目录..."
|
||||
mkdir -p "$BUILD_DIR"
|
||||
|
||||
# 清理旧文件
|
||||
echo "[信息] 清理旧文件..."
|
||||
rm -f "$BUILD_DIR"/*
|
||||
|
||||
# 导出项目
|
||||
echo "[信息] 开始导出Web版本..."
|
||||
"$GODOT_PATH" --headless --export-release "$EXPORT_PRESET" "$BUILD_DIR/index.html"
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "[错误] 导出失败！"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 生成部署信息
|
||||
echo "[信息] 生成部署信息..."
|
||||
cat > "$BUILD_DIR/deploy_info.json" << EOF
|
||||
{
|
||||
"project": "$PROJECT_NAME",
|
||||
"version": "1.0.0",
|
||||
"build_time": "$(date)",
|
||||
"platform": "web"
|
||||
}
|
||||
EOF
|
||||
|
||||
echo
|
||||
echo "========================================"
|
||||
echo " 导出完成！"
|
||||
echo "========================================"
|
||||
echo "导出位置: $BUILD_DIR/"
|
||||
echo
|
||||
echo "下一步:"
|
||||
echo "1. 运行 scripts/serve_web.sh 进行本地测试"
|
||||
echo "2. 将 $BUILD_DIR/ 目录上传到Web服务器"
|
||||
echo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 生产环境部署
|
||||
|
||||
### 1. 文件上传清单
|
||||
确保上传以下文件到Web服务器：
|
||||
```
|
||||
build/web/
|
||||
├── index.html # 主HTML文件
|
||||
├── index.js # JavaScript引导文件
|
||||
├── index.wasm # WebAssembly主文件
|
||||
├── index.pck # Godot资源包
|
||||
├── index.worker.js # Web Worker文件
|
||||
├── favicon.ico # 网站图标
|
||||
└── deploy_info.json # 部署信息（可选）
|
||||
```
|
||||
|
||||
### 2. 目录权限设置
|
||||
```bash
|
||||
# Linux服务器权限设置
|
||||
chmod 644 build/web/*
|
||||
chmod 755 build/web/
|
||||
```
|
||||
|
||||
### 3. 域名配置
|
||||
- 确保域名正确解析到服务器
|
||||
- 配置SSL证书（推荐使用Let's Encrypt）
|
||||
- 设置CDN加速（可选）
|
||||
|
||||
---
|
||||
|
||||
## 🔧 服务器配置
|
||||
|
||||
### Apache配置 (.htaccess)
|
||||
```apache
|
||||
# MIME类型配置
|
||||
AddType application/wasm .wasm
|
||||
AddType application/octet-stream .pck
|
||||
AddType application/javascript .js
|
||||
|
||||
# 启用压缩
|
||||
<IfModule mod_deflate.c>
|
||||
AddOutputFilterByType DEFLATE text/html text/css application/javascript application/wasm
|
||||
AddOutputFilterByType DEFLATE application/json application/xml
|
||||
</IfModule>
|
||||
|
||||
# 缓存控制
|
||||
<IfModule mod_expires.c>
|
||||
ExpiresActive On
|
||||
ExpiresByType application/wasm "access plus 1 month"
|
||||
ExpiresByType application/octet-stream "access plus 1 month"
|
||||
ExpiresByType application/javascript "access plus 1 week"
|
||||
ExpiresByType text/html "access plus 1 hour"
|
||||
</IfModule>
|
||||
|
||||
# CORS配置（如果需要）
|
||||
<IfModule mod_headers.c>
|
||||
Header set Access-Control-Allow-Origin "*"
|
||||
Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
|
||||
Header set Access-Control-Allow-Headers "Content-Type, Authorization"
|
||||
|
||||
# SharedArrayBuffer支持
|
||||
Header set Cross-Origin-Embedder-Policy "require-corp"
|
||||
Header set Cross-Origin-Opener-Policy "same-origin"
|
||||
</IfModule>
|
||||
|
||||
# 安全配置
|
||||
<IfModule mod_headers.c>
|
||||
Header always set X-Content-Type-Options nosniff
|
||||
Header always set X-Frame-Options DENY
|
||||
Header always set X-XSS-Protection "1; mode=block"
|
||||
</IfModule>
|
||||
```
|
||||
|
||||
### Nginx配置
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
listen 443 ssl http2;
|
||||
server_name yourdomain.com;
|
||||
|
||||
# SSL配置
|
||||
ssl_certificate /path/to/certificate.crt;
|
||||
ssl_certificate_key /path/to/private.key;
|
||||
|
||||
root /var/www/whaletown/build/web;
|
||||
index index.html;
|
||||
|
||||
# MIME类型
|
||||
location ~* \.wasm$ {
|
||||
add_header Content-Type application/wasm;
|
||||
expires 1M;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
location ~* \.pck$ {
|
||||
add_header Content-Type application/octet-stream;
|
||||
expires 1M;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
location ~* \.js$ {
|
||||
add_header Content-Type application/javascript;
|
||||
expires 1w;
|
||||
}
|
||||
|
||||
# 压缩配置
|
||||
gzip on;
|
||||
gzip_vary on;
|
||||
gzip_min_length 1024;
|
||||
gzip_types
|
||||
text/html
|
||||
text/css
|
||||
application/javascript
|
||||
application/wasm
|
||||
application/json;
|
||||
|
||||
# CORS配置
|
||||
add_header Access-Control-Allow-Origin "*" always;
|
||||
add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
|
||||
add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;
|
||||
|
||||
# SharedArrayBuffer支持
|
||||
add_header Cross-Origin-Embedder-Policy "require-corp" always;
|
||||
add_header Cross-Origin-Opener-Policy "same-origin" always;
|
||||
|
||||
# 安全头
|
||||
add_header X-Content-Type-Options nosniff always;
|
||||
add_header X-Frame-Options DENY always;
|
||||
add_header X-XSS-Protection "1; mode=block" always;
|
||||
|
||||
# 主页面
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
|
||||
# API代理（如果需要）
|
||||
location /api/ {
|
||||
proxy_pass https://whaletownend.xinghangee.icu/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ 性能优化
|
||||
|
||||
### 1. 资源优化
|
||||
- **纹理压缩**: 启用VRAM纹理压缩
|
||||
- **音频压缩**: 使用OGG格式，调整比特率
|
||||
- **模型优化**: 减少多边形数量，优化LOD
|
||||
|
||||
### 2. 代码优化
|
||||
```gdscript
|
||||
# 在Web平台禁用不必要的功能
|
||||
func _ready():
|
||||
if OS.has_feature("web"):
|
||||
# 禁用文件系统操作
|
||||
# 优化渲染设置
|
||||
get_viewport().render_target_update_mode = Viewport.UPDATE_WHEN_VISIBLE
|
||||
```
|
||||
|
||||
### 3. 加载优化
|
||||
- 使用资源预加载
|
||||
- 实现渐进式加载
|
||||
- 显示加载进度
|
||||
|
||||
---
|
||||
|
||||
## 🐛 常见问题解决
|
||||
|
||||
### 1. SharedArrayBuffer错误
|
||||
**问题**: 控制台显示SharedArrayBuffer相关错误
|
||||
**解决**: 配置正确的HTTP头：
|
||||
```
|
||||
Cross-Origin-Embedder-Policy: require-corp
|
||||
Cross-Origin-Opener-Policy: same-origin
|
||||
```
|
||||
|
||||
### 2. 文件加载失败
|
||||
**问题**: WASM或PCK文件加载失败
|
||||
**解决**:
|
||||
- 检查MIME类型配置
|
||||
- 确保文件路径正确
|
||||
- 检查服务器权限
|
||||
|
||||
### 3. API请求失败
|
||||
**问题**: 网络请求被CORS阻止
|
||||
**解决**:
|
||||
- 配置服务器CORS头
|
||||
- 使用API代理
|
||||
- 检查API服务器配置
|
||||
|
||||
### 4. 性能问题
|
||||
**问题**: Web版本运行缓慢
|
||||
**解决**:
|
||||
- 启用WebGL2
|
||||
- 优化资源大小
|
||||
- 使用性能分析工具
|
||||
|
||||
### 5. 音频问题
|
||||
**问题**: 音频无法播放
|
||||
**解决**:
|
||||
- 用户交互后才能播放音频
|
||||
- 使用Web兼容的音频格式
|
||||
- 检查浏览器音频策略
|
||||
|
||||
---
|
||||
|
||||
## 📊 部署检查清单
|
||||
|
||||
### 导出前检查
|
||||
- [ ] Godot导出模板已安装
|
||||
- [ ] Web导出预设已配置
|
||||
- [ ] 项目设置已优化
|
||||
- [ ] 资源文件已压缩
|
||||
|
||||
### 部署前检查
|
||||
- [ ] 所有文件已上传
|
||||
- [ ] 服务器MIME类型已配置
|
||||
- [ ] CORS设置已配置
|
||||
- [ ] SSL证书已安装
|
||||
|
||||
### 部署后测试
|
||||
- [ ] 页面正常加载
|
||||
- [ ] 游戏功能正常
|
||||
- [ ] 网络请求正常
|
||||
- [ ] 音频播放正常
|
||||
- [ ] 移动端兼容性
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如果遇到问题，请检查：
|
||||
1. 浏览器开发者工具的控制台错误
|
||||
2. 网络请求是否成功
|
||||
3. 服务器配置是否正确
|
||||
4. Godot版本是否兼容
|
||||
|
||||
**更新日志**: 查看 `docs/web_deployment_changelog.md`
|
||||
Reference in New Issue
Block a user