whale-town-front/docs/web_deployment_guide.md

# 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`