Pygbag部署至局域网服务器后卡在Downloading界面的问题排查

一、浏览器加载卡顿（Cross-Origin/Feature Policy 错误） #

核心原因 #

局域网访问时，浏览器跨域安全策略阻止了资源加载，同时Feature Policy限制了pygbag所需的部分浏览器权限，导致资源下载停滞。

解决步骤 #

• 配置服务器CORS权限：
  若使用Nginx/Apache等Web服务器，需在配置中添加跨域允许头：

  # Nginx示例
  add_header Access-Control-Allow-Origin *;
  add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
  

  若直接用pygbag自带的服务器启动，可添加--cors参数：

  pygbag serve --cors
  

• 检查资源路径与权限：
  确认服务器上pygbag打包后的所有资源（.wasm、.js、静态资源文件）路径正确，文件权限设为644，目录权限设为755，确保浏览器能正常请求到资源。
• 修正Feature Policy限制：
  在服务器HTTP头中添加权限策略，允许pygbag所需的浏览器能力（比如音频、全屏）：

  add_header Permissions-Policy "fullscreen=(), audio=()";
  

二、服务器端Black警告 #

原因 #

pygbag的代码优化模块依赖Python格式化工具black，当前服务器环境未安装该工具，导致优化步骤跳过，但不影响项目运行。

解决方法 #

• 若无需代码优化，可直接忽略该警告；
• 若要消除警告，在服务器的Python虚拟环境中安装black：

  source /home/administrator/cloverdle/venv/bin/activate
  pip install black
  

内容的提问来源于stack exchange，提问作者Willregex