whale-town-front/docs/web_deployment_guide.md

Web部署完整指南

版本: 1.0.0
更新时间: 2025-12-25
适用于: Godot 4.5+ 项目

📋 目录

1. 导出准备
2. 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：

@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：

@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：

#!/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. 目录权限设置

# Linux服务器权限设置
chmod 644 build/web/*
chmod 755 build/web/

3. 域名配置

• 确保域名正确解析到服务器
• 配置SSL证书（推荐使用Let's Encrypt）
• 设置CDN加速（可选）

---

🔧 服务器配置

Apache配置 (.htaccess)

# 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配置

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. 代码优化

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