企业官网建设流程全解析

• 桌面应用
• 前端
• UI组件

本指南基于 docs/quickstart.md 编写，带你从零开始安装 Proton Native、初始化第一个桌面应用，并跑起带热重载的开发流程。读完你将掌握proton-native-cli的完整使用方式、AppRegistry入口约定、npm run start/npm run dev的区别，以及热重载背后的 webpack 与 react-proxy 原理。

Proton Native 是一个面向跨平台桌面应用的 React 环境（仓库项目描述为 "A React environment for cross platform desktop apps"），它使用与 React Native 相同的语法和组件，通过 Qt 渲染原生窗口，无需 Electron 也能构建桌面 GUI。本仓库当前为 V2 版本（见 package.json 中"version": "2.0.5"），V2 是一次彻底重写，引入了 flexbox 布局（基于 yoga-layout）、CSS 样式、热重载与proton-native-cli管理工具（详见 docs/v2_changes.md）。

环境要求与版本前提

在开始安装之前，先确认你的开发环境满足以下条件，尤其是 macOS 用户的 Node.js 版本问题——这是快速上手阶段最常遇到的坑。

Node.js 版本注意事项（macOS）

原文档开篇特别强调：在 macOS 上，Proton Native 在 Node 版本高于 12.13.1 以及高于 13.0.1 时无法正常工作。

根因是 Node.js 依赖的 libuv 存在一个 bug（即 libuv 仓库的 issue #2593，并已被报告到 Node.js 主仓库的 issue #31328），该问题在撰写本指南时仍未修复。因此在官方修复之前，建议在 macOS 上使用低于这些版本的 Node.js：

• 使用12.x 系列：请安装12.13.1或更低的版本；
• 使用13.x 系列：请安装13.0.1或更低的版本。

这类版本很容易通过版本管理工具安装，例如使用nvm：

nvm install 12.13.1 nvm use 12.13.1

注意：这一限制是 macOS 特有的（libuv 相关 bug 在该平台触发）。其他平台的版本要求相对宽松——V2 为 NAPI 2、3、4 三个版本编译了预构建二进制，覆盖 Linux、Mac、Windows 上的主流 Node.js 版本（见 docs/v2_changes.md 的「Difficult Installation」一节）。

Linux：安装 Qt 开发包

在 Linux 平台上，需要预先安装 Qt 的开发包才能正常运行 Proton Native 应用：

# Debian / Ubuntu 系列 sudo apt-get install qtbase5-dev

这是唯一列出的系统级前置依赖。Proton Native 的 Qt 后端正是通过node-qt-napi（一个为 Proton Native 定制的 Node.js Qt 绑定）来创建窗口与控件，详见仓库 src/backends/index.ts 的后端抽象与 src/components/Window.ts 的窗口组件实现。qtbase5-dev提供运行时所需的 Qt 动态库，缺失时应用启动阶段会直接失败。

安装与初始化项目

自动方式：一行命令创建项目（推荐）

原文档给出的标准安装流程使用npx直接调用 CLI，无需先全局安装任何东西：

# 通过 cli 应用创建项目 npx proton-native-cli init my-app # 进入项目目录 cd my-app # 运行你的应用 npm run start # 或者使用热重载模式运行 npm run dev

npx proton-native-cli init my-app会创建一个名为my-app的完整可运行项目，其中已经内置了 Babel 编译、webpack 打包和热重载所需的一切配置。

备用方式：全局安装 CLI

如果你更习惯全局工具，docs/v2_changes.md 的「To get started」一节还提供了等价的全局安装方式：

# 全局安装 cli 应用 npm install -g proton-native-cli # 创建项目（命令变为直接调用 proton-native） proton-native init my-app # 进入项目目录 cd my-app # 运行你的应用 npm run start # 或者使用热重载模式运行 npm run dev

两种方式生成的项目骨架完全一致，按个人习惯选择其一即可。

初始化后的项目结构

以仓库自带的 examples/Calculator 为例，一个典型的 Proton Native 项目包含：

my-app/ ├── index.js # 入口文件：注册根组件 + 热重载接收逻辑 ├── app.js # 业务组件：默认导出你的根组件 ├── webpack.config.js # webpack 配置：打包 + 开发模式热重载 └── package.json # 依赖与 npm scripts

其中package.json的 scripts 与示例仓库一致：

{ "scripts": { "start": "babel-node index.js", "dev": "webpack --mode=development", "webpackRun": "babel-node dist/index.out.js", "build": "babel index.js -d bin/" } }

• start直接用babel-node运行index.js，适合简单启动；
• dev用 webpack 开发模式打包并监听文件变化，启动热重载；
• webpackRun由 webpack 构建完成后自动调用，用于拉起打包产物。

运行你的应用：start 与 dev 的区别

这是快速上手最核心的两个命令，理解它们的行为差异能帮你避免"改了代码没反应"的困惑。

npm run start：普通启动

npm run start等价于执行babel-node index.js，直接解释执行你的入口文件。它不包含任何文件监听与热重载能力，适合正式验证一个完整功能或简单跑通流程。

npm run dev：带热重载的开发模式

npm run dev等价于执行webpack --mode=development，它：

1. 以index.js为入口（见 examples/Calculator/webpack.config.js 中的entry: ['./index.js']）；
2. 开启watch: true监听源码变化，并注入HotModuleReplacementPlugin与webpack/hot/poll?100热更新入口；
3. 每次构建完成（afterEmit钩子）后自动执行npm run webpackRun（即babel-node dist/index.out.js）拉起应用进程；
4. 生成dist/index.out.js单文件产物。

代码改动后，webpack 增量构建并把更新推送给运行中的应用，界面即时刷新且不丢失状态。关于热重载的详细机制见下文「热重载工作原理」一节。

理解应用入口：AppRegistry 约定

所有 Proton Native 应用都遵循"在app.js中定义组件、在index.js中注册组件"的约定。以 examples/Calculator/index.js 为例：

import React from 'react'; import { AppRegistry } from 'proton-native'; import Calculator from './app'; // 注册根组件并渲染 AppRegistry.registerComponent('calculator', <Calculator />); // ================================================================================ // 以下为热重载逻辑（生产构建时会被 webpack 剥离） // 此部分不应修改 if (module.hot) { module.hot.accept(['./app'], function() { const app = require('./app')['default']; AppRegistry.updateProxy(app); }); }

而你的根组件（如 examples/Calculator/app.js）从proton-native引入App、Window、View、Text、TouchableOpacity等组件，构建出完整的窗口 UI，并作为默认导出暴露给index.js。

AppRegistry 的底层实现

AppRegistry来自 src/render/index.ts，其核心逻辑是：

const AppRegistry = { registerComponent: (name: string, component: React.ComponentType) => { const newComponent = process.env.NODE_ENV === "production" ? component : hot(component); connectDevtools(DesktopRenderer); ROOT_NODE = createElement("ROOT", {}); container = DesktopRenderer.createContainer(ROOT_NODE); DesktopRenderer.updateContainer(newComponent, container, null); }, updateProxy: (app: any) => { if (container) { hot(app); container._reactInternalInstance = container.current; deepForceUpdate(container); } } };

从中可以看到几个关键事实：

• registerComponent(name, component)接收组件实例（而非组件类），通过react-reconciler的createContainer/updateContainer创建并挂载整个 React 树；
• 当NODE_ENV为production时，组件不会被hot()包装，即生产模式下自动禁用热重载；
• updateProxy(app)在收到模块更新通知后被调用，借助react-proxy保留旧状态并强制更新整棵组件树（deepForceUpdate）。

AppRegistry与全部组件（Window、View、App、Text、TextInput、Image、Button、Picker等）统一从包入口 src/index.ts 导出，这也正是示例代码import { AppRegistry, Window, ... } from 'proton-native'的对应关系。

热重载工作原理

热重载能力在proton-native-cli生成的项目中开箱即用（详见 docs/hot_reloading.md）。它的整体链路是webpack 监听 → 推送更新 → react-proxy 保状态刷新：

1. 项目自带的 webpack.config.js 把所有代码打包成dist/index.out.js单文件，并开启文件监听；
2. 变更信息通过module.hot（webpack HMR）传递给你的index.js；
3. index.js收到更新后，用AppRegistry.updateProxy(app)拉取最新组件版本；
4. react-proxy（仅在开发模式启用）让组件状态保持不变，同时用react-deep-force-update强制刷新整棵 React 树。

配置层面，开发模式的差异全部集中在 examples/Calculator/webpack.config.js 的这段逻辑中：

if (argv.mode === 'development') { config.mode = 'development'; config.plugins.push(new webpack.HotModuleReplacementPlugin()); config.devtool = 'source-map'; config.watch = true; config.stats = 'errors-only'; config.entry.unshift('webpack/hot/poll?100'); }

即开发模式额外启用 HMR 插件、轮询热更新入口与源码地图，并通过nodeExternals将webpack/hot/dev-server等模块加入白名单，确保它们在打包产物中保持可用。

热重载的注意事项（Gotchas）

原文档列出了几项实践约束，违反它们会导致热重载异常：

• 不要在app.js中注册组件，注册动作只应出现在index.js；
• 确保根组件是app.js的默认导出（export default），因为热更新回调通过require('./app')['default']获取组件；
• 当前版本的热重载暂不兼容 Redux；
• 不兼容 class 实例属性（受限于react-proxy）。规避方式是改为"用函数返回该值"——examples/Calculator/app.js 中getButtons()方法的注释正是这一约束的实践佐证："this can't be an instance variable or else it won't get hot reloaded"（这里不能使用实例变量，否则无法热重载）。

常见问题排查

• macOS 上应用无法启动：请先检查 Node 版本是否高于 12.13.1 / 13.0.1，若高于则用nvm降级后再试；
• Linux 上启动报 Qt 相关错误：确认已安装qtbase5-dev（sudo apt-get install qtbase5-dev）；
• npm run dev后界面没有刷新：确认改动的是app.js且根组件是默认导出，同时确认组件注册只存在于index.js；
• 想禁用热重载：将NODE_ENV设置为production即可（registerComponent内部据此跳过hot()包装）。

进一步学习

• docs/v2_changes.md：V2 完整改版说明，包括 Qt 选型、yoga flexbox、样式系统与安装方式演进；
• docs/hot_reloading.md：热重载的官方文档与全部 Gotchas；
• examples/Calculator：仿 iOS 计算器完整示例，包含组件拆分、样式与状态管理；
• examples/CatApi：集成 Redux +node-fetch的完整应用示例；
• docs/components/Window.md 与 docs/components/View.md：核心组件 API 参考；
• src/render/index.ts 与 src/index.ts：入口注册与组件导出的源码实现。

至此，你已经完成了从环境检查、项目初始化、命令启动到热重载原理的完整入门闭环。接下来就可以仿照examples/中的项目，用你熟悉的 React 语法开始编写自己的跨平台桌面应用了。

• 桌面应用
• 前端
• UI组件