企业官网建设流程全解析

• 跨平台
• 移动开发
• 前端

本文基于 Hippy 官方仓库中的《Hippy-Vue 常见反馈》文档（docs/api/hippy-vue/feedback.md）展开，聚焦 Hippy-Vue 开发者高频咨询的四个问题：如何快速启动一个 Hippy-Vue 项目、为什么模板中span里的换行符会被 trim、hippy-vue-next-style-parser包的具体职责，以及 Hippy 对 Vite 构建的支持情况。结合仓库源码，本文进一步还原了trimWhitespace配置在 hippy-vue 与 hippy-vue-next 两条渲染链路中的真实执行路径，并给出可直接复制的工程化配置示例，帮助读者把"文档结论"落到"源码可验证"的层面。

一、如何开始一个 Hippy-Vue 项目

官方反馈文档给出的第一建议是：参考官方文档与 demo 起步。在仓库内，文档与示例的具体落点如下：

• 入门文档：hippy-vue 介绍、核心组件、样式、Vue 3.x 说明；
• 可运行的示例工程：
  • driver/js/examples/hippy-vue-demo（hippy-vue / Vue 2 技术栈）
  • driver/js/examples/hippy-vue-next-demo（hippy-vue-next / Vue 3 技术栈）
  • driver/js/examples/hippy-vue-next-ssr-demo（Vue 3 + SSR 场景）

以 hippy-vue-demo 的 package.json 为例，一个标准的 Hippy-Vue 工程具备如下脚本与依赖：

{ "scripts": { "hippy:dev": "node ./scripts/env-polyfill.js hippy-dev -c ./scripts/hippy-webpack.dev.js", "hippy:vendor": "node ./scripts/env-polyfill.js webpack --config ./scripts/hippy-webpack.ios-vendor.js --config ./scripts/hippy-webpack.android-vendor.js --config ./scripts/hippy-webpack.ohos-vendor.js", "hippy:build": "node ./scripts/env-polyfill.js webpack --config ./scripts/hippy-webpack.ios.js --config ./scripts/hippy-webpack.android.js --config ./scripts/hippy-webpack.ohos.js", "web:dev": "npm run hippy:dev & node ./scripts/env-polyfill.js webpack serve --config ./scripts/hippy-webpack.web-renderer.dev.js", "web:build": "node ./scripts/env-polyfill.js webpack --config ./scripts/hippy-webpack.web-renderer.js" }, "dependencies": { "@hippy/vue": "3.3.1-rc.1", "@hippy/vue-native-components": "v3.3-latest", "@hippy/vue-router": "v3.3-latest", "vue": "^2.6.10", "vue-router": "^3.1.3" } }

从中可以归纳出工程结构要点：

1. 双入口约定：demo 通过webMain: "./src/main-web.js"与nativeMain: "./src/main-native.js"分别声明 Web 端与原生端的入口，实现同一套业务代码向 Web 渲染器与原生渲染器的双端输出；
2. 分平台产物：hippy:vendor/hippy:build会为 iOS、Android、OHOS 三端分别生成 vendor 包与业务包（demo 中还额外提供了 hermes 引擎变体脚本hippy:vendor:hermes、hippy:build:hermes）；
3. 核心 npm 依赖：@hippy/vue（框架适配层）、@hippy/vue-native-components（modal、view-pager、tab-host、ul-refresh 等原生组件扩展）、@hippy/vue-router（路由），以及原生vue与vue-router。

入口文件的典型写法可参考 hippy-vue-demo 的 main-native.js：通过new Vue({ appName, rootView, render, iPhone })声明应用，其中appName是终端侧注册的 App 名称，rootView: '#root'指定根节点挂载点，根节点挂载时才会触发上屏。

二、Hippy-Vue 中 span 的换行符为什么会被 trim

这是官方反馈中技术含量最高的一条问题。官方文档给出的结论是：3.x 版本的 hippy-vue 默认开启了Vue.config.trimWhitespace参数，而 2.x 版本是关闭的，这样做的目的之一是对齐 Vue 3 对未来版本的白空格处理规划。下面结合仓库源码验证这一结论。

2.1 默认值：hippy-vue 包内硬编码开启

在 hippy-vue 包入口 中，可以看到框架对默认配置的声明：

Vue.config.silent = false; Vue.config.trimWhitespace = true; setVue(Vue);

也就是说，从 3.x 系列（对应仓库内@hippy/vue3.x 版本）开始，trimWhitespace的默认值就是true。示例工程也在入口文件中显式设置了该参数，hippy-vue-demo 的 main-native.js 中的注释说明了它的语义：

/** * whether to trim whitespace on text element, * default is true, if set false, it will follow vue-loader compilerOptions whitespace setting */ Vue.config.trimWhitespace = true;

注释同时提示了一个重要的行为边界：设为false之后，白空格行为会回退到 vue-loader 编译器选项whitespace的设置，即交给模板编译器自行决定。

2.2 运行时执行链路：whitespaceFilter 在哪里生效

hippy-vue 中该配置的运行时消费点在 whitespaceFilter 工具函数：

function whitespaceFilter(str: string) { if (typeof str !== 'string') return str; // Adjusts template whitespace handling behavior. // "trimWhitespace": default behavior is true. // It will trim leading / ending whitespace including all special unicode such as \xA0( ). if (!_Vue || typeof _Vue.config.trimWhitespace === 'undefined' || _Vue.config.trimWhitespace) { return str.trim().replace(/( |Â)/g, ' '); } return str.replace(/( |Â)/g, ' '); }

可以确认三个细节：

• 该函数会读取全局_Vue.config.trimWhitespace，当参数未定义时按开启处理（typeof ... === 'undefined' || _Vue.config.trimWhitespace），与"3.x 默认开启"的文档描述完全一致；
• 开启时不仅trim()首尾空白，还会把 这类特殊 unicode 占位替换为普通空格；
• 即使关闭， 替换逻辑仍然执行，只是不再做首尾裁剪。

这个过滤器最终作用在文本属性上。在 hippy-vue 的元素属性处理逻辑 中，TEXT、VALUE、DEFAULT_VALUE、PLACEHOLDER这类文本相关属性在写入前都会经过whitespaceFilter：

case ATTRIBUTE_KEY_MAP.TEXT: case ATTRIBUTE_KEY_MAP.VALUE: case ATTRIBUTE_KEY_MAP.DEFAULT_VALUE: case ATTRIBUTE_KEY_MAP.PLACEHOLDER: { // ... if (!options || !options.textUpdate) { // white space handler value = whitespaceFilter(value); } value = unicodeToChar(value); break; }

hippy-vue-next（Vue 3 版）的链路略有不同：配置项由createHippyApp的选项传入，HippyAppOptions 接口 中定义了trimWhitespace?: boolean字段，并在应用创建时调用 setTrimWhitespace 落地到模块级变量；其 whitespaceFilter 实现 依据该变量决定是str.trim()还是原样返回，并在 hippy-element.ts 的文本属性处理 处消费。官方示例 hippy-vue-next-demo 的 main-native.ts 中同样显式传入了trimWhitespace: true。

从源码结构看，两条渲染链路（hippy-vue / hippy-vue-next）都把"是否裁剪空白"的控制权暴露给了业务侧，这正是官方反馈给出两种解决方案的前提。

2.3 官方给出的两种解决方案

方案 a：关闭 trim，与安卓版本行为完全对齐。在 hippy.js（即业务入口文件）中加一句：

// hippy-vue 2.x 风格（Vue 2 运行时） Vue.config.trimWhitespace = false;

hippy-vue-next 项目则改为在createHippyApp的选项中传trimWhitespace: false。官方同时提醒：这个参数会对产物有一定影响，建议前端同事重新评估，尤其是依赖"模板换行即视觉换行"的存量页面。

方案 b：换行不依赖span内的空白字符。由于 Hippy 原生渲染不提供<br>标签，也没有white-space相关 CSS 的支持（从仓库样式文档 docs/api/style/ 覆盖的布局、外观、颜色等章节也可以印证，样式系统并不包含 Web CSS 的空白模型），需要换行时应拆成独立的text文本组件，而不是在同一个span中写多行文本。例如：

<!-- 不推荐：多行写在同一个 span 内，首尾空白会被裁剪 --> <span>第一行 第二行</span> <!-- 推荐：每个逻辑行使用独立文本节点 --> <text>第一行</text> <text>第二行</text>

这一方案不受trimWhitespace配置影响，跨端行为最稳定。

三、hippy-vue-next-style-parser 包的作用

官方反馈对该包的一句话定位是：用于处理 vue-next 的 CSS parse 和 match 逻辑。在仓库中，该包位于driver/js/packages/hippy-vue-next-style-parser，其 入口导出 清晰地划分了两组能力：

export * from './style-parser/css-parser'; export { translateColor } from './style-parser/color-parser'; export * from './style-match';

• style-parser（解析）：src/style-parser/css-parser.ts负责把 CSS 声明解析为结构化样式数据，src/style-parser/color-parser.ts提供translateColor，把#hex、颜色名、rgba()等颜色写法换算为 Hippy 终端需要的数值型颜色（这一能力与示例工程中backgroundColor: 4282431619这类"预转换颜色值"的注释相呼应，参见 hippy-vue-next-demo 入口）；
• style-match（匹配）：src/style-match/目录下包含css-selectors.ts（选择器模型）、css-selectors-match.ts（选择器与元素匹配）、css-map.ts（样式表映射）、css-append.ts（样式追加/合并）与parser.ts，共同支撑 hippy-vue-next 在运行时把 class 选择器匹配到具体元素节点上。

该包还配有独立测试：__test__/style-parser/下的css-parser.test.ts、color-parser.test.ts，以及__test__/style-match/下的parser.test.ts、css-append.test.ts等，覆盖了 CSS 解析与选择器匹配两条主链路。

从源码结构看，可以推断 hippy-vue-next 的样式体系与 hippy-vue（2.x）不同：它没有把样式完全交给 Webpack 的 css-loader 在构建期编译完，而是把"解析 + 匹配"的核心逻辑抽成了独立的运行时包，以便 Vue 3 技术栈下的hippy-vue-css-loader、SSR 场景与端内运行时复用同一套实现。业务侧如果定制样式处理（如示例中的styleOptions.beforeLoadStyle钩子处理 rem 单位），其输入输出的数据结构即来自该包导出的声明类型。

四、Hippy 是否支持 Vite 构建

官方反馈给出的答复是：已支持，但目前只有腾讯内部版。

对仓库使用者而言，需要明确适用的前提与限制：

1. 开源仓库当前随示例工程提供的构建工具链是 Webpack。driver/js/examples/下三个 Vue 示例（hippy-vue-demo、hippy-vue-next-demo、hippy-vue-next-ssr-demo）的构建脚本全部基于 Webpack 配置文件（如scripts/hippy-webpack.ios.js、scripts/hippy-webpack.dev.js），配套@hippy/hippy-hmr-plugin、@hippy/hippy-dynamic-import-plugin等 Webpack 插件实现热更新与动态加载；
2. Vite 方案按文档口径属于腾讯内部能力，公开仓库中没有对应的 Vite 配置或插件可供直接使用，因此本文不展开具体配置；腾讯系业务按文档提示联系"端框架小助手"获取，外部团队若评估 Vite 迁移，应以仓库内 Webpack 工具链为基准进行对比验证。

小结

围绕 Hippy-Vue 的这四类常见反馈，可以形成一张排查速查表：

以上每一条结论均可在仓库内对应文件直接查证，便于在集成 Hippy-Vue 遇到问题时快速定位配置项与源码行为。

• 跨平台
• 移动开发
• 前端