React 360 应用生产构建与发布指南：使用 `npm run bundle` 打包并部署到 Web 服务器

• 前端
• 3D渲染

本地开发服务器（packager）只适合开发调试。当你准备把 React 360 应用正式上线时，需要通过生产构建把代码打包成可直接部署的静态资源。本文以 docs/publish.md 为核心，结合仓库内 scripts/bundle.js、scripts/project-paths.js、CLI 模板生成器（addons/react-360-cli/generators）与示例应用（Samples/BasicAppTemplate）等源码实现，完整讲解npm run bundle的命令用法、构建产物目录结构、静态资源（static_assets）的部署策略，以及如何通过assetRoot把资源迁移到独立域名或 CDN。

读完本文，你将掌握：如何一键生成生产版 JS 与 HTML、构建产物应如何摆放才能被服务器正确解析、asset()/staticResourceURL()在发布前后的行为差异，以及如何用--assets参数在打包时注入自定义 CDN 资源地址。

为什么需要生产构建

React 360 开发阶段通过 scripts/packager.js 在本地启动开发服务器，代码以未压缩、带 source map 的形式按需提供，页面通过 Samples/BasicAppTemplate/index.html 中的开发 URL 加载 bundle：

<script src="./client.bundle?platform=vr"></script> <script> React360.init( 'index.bundle?platform=vr&dev=true', document.getElementById('container'), { bridgeFile: 'NonBlobBridge.js', assetRoot: 'static_assets/', } ); </script>

这种模式下 URL 带有?platform=vr查询参数，bundle 依赖开发服务器动态解析，不能直接放到生产服务器上使用。因此 React 360 提供了一条一键命令，把所有代码打包成单文件夹的静态版本，交给任意 Web 服务器托管即可。

一键构建：npm run bundle

在项目根目录（即包含package.json、且其dependencies中声明了react-360的目录）执行：

npm run bundle

这条命令在 CLI 生成的项目模板中被定义为node node_modules/react-360/scripts/bundle.js（见 addons/react-360-cli/generators/package.json.generator.js）。构建过程的核心逻辑位于 scripts/bundle.js，主要完成四件事：

1. 定位项目目录：通过 scripts/project-paths.js 从当前目录向上查找包含react-360依赖的package.json；也可用环境变量PROJECT_LOCATION显式指定项目位置。找不到项目时直接报错Could not find a React 360 project directory并退出。
2. 并行打包两份 JS：分别以index.js（React 应用入口）和client.js（React 360 Web 运行时入口）为入口，调用 React Native CLI 的bundle命令，产出index.bundle.js与client.bundle.js。关键参数包括：
   • --platform vr：按 VR 平台生成 bundle；
   • --dev false：关闭开发模式，得到生产压缩版本；
   • --assets-dest build：将打包内联的资源输出到build目录。
3. 重写index.html：把开发 URL（client.bundle?platform=vr、index.bundle?platform=vr&dev=true）替换为生产文件名（client.bundle.js、index.bundle.js），并写入构建目录。
4. 复制桥接文件：从index.html中解析bridgeFile配置（默认NonBlobBridge.js），将该文件复制到构建目录。

构建成功后会看到提示：

Production versions of JS were successfully built. They can be found at <项目根目录>/build

构建产物与服务器目录结构

npm run bundle会在项目根目录创建build文件夹，内容大致如下：

build/ ├─ index.html # 已改写为指向生产 bundle 的 HTML ├─ index.bundle.js # React 应用（index.js）的生产压缩包 ├─ client.bundle.js # React 360 运行时（client.js）的生产压缩包 └─ NonBlobBridge.js # 桥接文件

发布时把该目录内容整体复制到服务器，再补上static_assets文件夹，最终布局与 docs/publish.md 给出的结构一致：

Web Server ├─ static_assets/ │ ├─ index.html ├─ index.bundle.js ├─ client.bundle.js └─ NonBlobBridge.js

关于 bridge 文件的说明：copyBridgeFile会优先从项目index.html的bridgeFile: 'xxx.js'配置中解析实际文件名（见 scripts/bundle.js）。若找不到index.html或桥接文件，构建脚本会打印警告，提示需要手动复制。

静态资源：开发与生产的差异

docs/static-assets.md 指出：应用中的图片、全景图、声音和 3D 模型等资源可以托管在外部服务，也可以自行托管。区别在于发布阶段：外部托管的资源位置不变，可直接引用；自行托管的资源在开发（static_assets目录）与生产（服务器其他位置）之间可能迁移，需要特殊处理。

用asset()引用资源，而不是写死相对路径

为让资源地址在生产期可被改写，应避免手写相对 URL，统一使用asset()方法。默认情况下它指向static_assets目录，运行时可重写为 CDN 地址（即使该 URL 是动态生成的）：

// 默认指向 static_assets/myImage.png <Image source={asset('myImage.png')} />

其底层实现见 Libraries/Utilities/asset.js：asset(localPath)返回{uri: staticAssetURL(localPath)}形式的资源对象；而 Libraries/Utilities/staticAssetURL.js 会读取NativeModules.ExternalAssets暴露的assetRoot，把本地路径拼接到资源根路径之后，从而在运行时完成地址迁移。

需要纯字符串路径时用staticResourceURL()

asset()返回的是资源对象（带uri字段），某些场景（如直接给 API 传路径字符串）只需一个字符串地址，此时可用staticResourceURL()：它接收本地资源路径，并在静态资源位置变化时自动转换。它与asset()共用同一套staticAssetURL底层逻辑，只是返回类型不同。

指定资源位置：assetRoot与--assets

初始化时指定assetRoot

应用发布后，可在初始化ReactInstance时传入assetRoot配置静态资源位置：

const r360 = new ReactInstance( 'MyReact360App.bundle.js', document.getElementById('container'), { // 提供自定义资源根路径 assetRoot: 'https://mycdn.example.net/myapp/', }, );

参考示例 Samples/BasicAppTemplate/client.js，初始化逻辑位于ReactInstance中，开发模板默认assetRoot: 'static_assets/'（见 addons/react-360-cli/generators/index.html.generator.js）。

打包时用--assets注入

如果使用npm run bundle构建，可用--assets标志在打包阶段指定自定义资源根：

npm run bundle -- --assets "https://mycdn.example.net/myapp/" # 或使用 yarn yarn bundle --assets "https://mycdn.example.net/myapp/"

构建脚本 scripts/bundle.js 解析--assets参数：若末尾没有/会自动补全，随后在重写index.html时，将assetRoot: 'static_assets/'替换为你提供的值（见updateHTML逻辑，scripts/bundle.js）。若index.html中找不到static_assets/字样，脚本会打印Could not find assetRoot警告，提醒手动修改。

发布检查清单

1. 在项目根目录执行npm run bundle，确认输出提示构建成功。
2. 将build目录下所有文件（index.html、index.bundle.js、client.bundle.js、NonBlobBridge.js）复制到服务器。
3. 若应用使用了static_assets目录中的资源，将该目录一并复制到服务器（与index.html同级）。
4. 若资源部署在独立域名或 CDN，用--assets重新打包，或在客户端初始化时传入assetRoot。
5. 访问服务器上的index.html验证：页面能正常加载、全景背景与资源正常显示。

补充：从源码看构建流程的边界与限制

• buildScript依赖node_modules中 React Native 的 CLI（react-native/local-cli/cli.js），可通过环境变量RN_CLI_LOCATION覆盖（scripts/bundle.js）。因此请确保项目已正确安装依赖。
• updateHTML与copyBridgeFile在找不到index.html、找不到bridgeFile或写入失败时，只会打印警告而不会中断构建（scripts/bundle.js），发布前需留意终端输出的**警告项，必要时手动修正build/index.html中的路径。
• 构建目录若已存在会直接复用，不会清空旧产物；build目录不存在时由脚本自动创建（scripts/bundle.js）。

• 前端
• 3D渲染