企业官网建设流程全解析

做跨端开发这几年，我踩过最多的坑，几乎都集中在同一件事上：同一套代码，在H5上跑得好好的，一编译到微信小程序就变了样；明明是同一条登录逻辑，App端和Web端的实现方式完全不同，一个走原生SDK回调，一个走OAuth跳转。很多人第一反应就是写运行时判断，用uni.getSystemInfoSync().platform去切分支，结果代码越来越胖，每个平台都背着另外几个平台的分支在运行，包体变大、逻辑变乱、后期维护更是噩梦。uni-app条件编译，就是为了根治这个问题而生的。它把平台差异化处理从运行时挪到编译期，在打包那一刻就把不属于当前平台的代码“裁掉”，让产物干净、体积更小、逻辑更清晰。我会从机制、语法、实战场景和坑位排查几个角度，把这套跨端开发中的核心利器讲透。这篇文章适合正在用uni-app做多端小程序和App、又被平台差异折磨的开发者。

1. 条件编译的核心机制：编译期裁切而非运行时判断

1.1 条件编译与运行时判断的本质区别

先弄清楚一个最基础的问题：条件编译到底在做什么。它跟你在业务代码里写的if (platform === 'weixin')完全是两回事。运行时判断是在程序跑起来之后，靠系统信息去决定走哪个分支，代码里每一个平台的分支都会被完整打包进产物里，用户手机上其实装着所有平台的代码，只是执行的时候只进其中一个分支。条件编译恰好相反，它发生在编译阶段，HBuilderX在打包之前就已经把条件编译指令标注的代码块整体删除，最终产物里根本不存在其他平台的代码。

我打个比方。运行时判断就像你请了三位厨师，让他们同时站在厨房里，菜来了之后看菜单是哪个菜系，再让对应的厨师上手，但另外两位厨师的工资你还是得照付；条件编译则是接待顾客之前就已经只留一位厨师，另外两位压根没进场，后厨成本自然更低。对应到代码上，就是包体积更小、逻辑分支更少、运行效率更高，而且某些平台特有的API不会意外混入其他平台导致报错。

实际业务里，有些场景确实只能靠运行时判断，比如根据手机型号做UI适配、不同系统设置状态栏高度，这些是与用户环境强相关的行为，必须在运行时动态计算。而像“微信小程序才有的分享参数”“App端才有的推送配置”这类编译期就能确定的平台差异，就应该用条件编译提前切好。区分标准也很简单：这个差异在打包那一刻是不是已经注定？如果是，就交给条件编译；如果跟用户实际操作有关，才考虑运行时判断。

1.2 条件编译覆盖的语言范围

很多人以为条件编译只是用来切JS逻辑，其实它覆盖的范围远比你想象的大。在uni-app项目里，你可以在这些位置使用条件编译：

• JS/TS文件：包括普通js、vue文件中的script块、工具函数等，用// #ifdef行注释形式，适合切API实现、mock数据、第三方SDK引用。
• Vue模板：在template里用<!-- #ifdef -->形式，可以整块隐藏或替换节点，比如微信小程序才显示某个按钮、App端才渲染某个组件。
• 样式：在style里用/* #ifdef */形式，可以给不同平台写完全不同的样式规则，解决各端默认样式不一致的问题。
• pages.json：很多人会忽略这一块，这里的页面配置、tabBar配置、分包配置都可以用条件编译。简单说，你可以让H5端没有某个页面，而微信小程序端有。
• manifest.json：应用的权限声明、SDK配置、App图标启动图等也能用条件编译，在发布多端应用时特别有用。
• 静态资源路径：虽然static目录本身不支持条件编译，但你完全可以在JS或模板里用条件编译引用不同的资源路径，达到“同一语句在不同平台加载不同图片”的效果。

熟悉这套覆盖面之后，你就会发现条件编译不只是“代码层面的if”，它其实是一套贯穿项目所有配置文件的平台隔离方案。我个人更愿意把它理解成“编译期的预处理”，只要你遵守注释语法，就能在任何配置形态的文件里做平台差异化。

2. 五大平台条件编译语法与实操细节

2.1 JS中的条件编译写法

JS里最基础的写法是这样：

// #ifdef H5 import { h5Login } from '@/api/h5Login' // #endif // #ifdef MP-WEIXIN import { wxLogin } from '@/api/wxLogin' // #endif

所有// #ifdef 平台标识开始的代码块，必须用// #endif结束。中间可以写任意多行普通代码，但指令行写错或漏掉#endif，编译器就会报错或静默不生效。写的时候注意，指令那两行必须是完整独立的一行注释，不要跟其他代码混在同一行，比如const a = 1 // #ifdef H5这种写法就可能出问题。

平台标识有哪些具体值，我把常用的整理成了一张表：

用#ifdef表示“只在这个平台编译”，用#ifndef表示“除了这个平台之外都编译”。两者是互补的关系，有时候用#ifndef可以少写几个平台，代码显得更干净。比如想要“除了微信小程序之外都用A方案”，可以写成// #ifndef MP-WEIXIN，这样就省掉了罗列H5、App、支付宝等多端的大片代码。

这里要特别提醒一点：JS里的条件编译使用的是行注释，不是块注释。也就是必须用//而不是/* */。我之前见过有人图省事，在JS文件里用/* #ifdef H5 */包裹代码，结果编译阶段完全没识别，代码也被当成普通注释处理，白白排查了半天。记住，JS就用//，不要混用。

2.2 模板与样式的条件编译写法

模板中的条件编译用到的是HTML注释形式：

<!-- #ifdef MP-WEIXIN --> <button open-type="share">分享给好友</button> <!-- #endif --> <!-- #ifndef MP-WEIXIN --> <view>非微信小程序端展示的占位内容</view> <!-- #endif -->

这招在“平台特有组件”的场景里特别管用。比如微信小程序的open-type="share"按钮在H5上根本没有意义，App端如果想实现分享得用原生SDK，你总不能在每个页面都写一堆v-if加运行时平台判断吧？用条件编译包一下，让每个平台只渲染它需要的节点，整个模板看起来干净很多。

样式里的条件编译用的是CSS注释：

/* #ifdef H5 */ .page { height: 100vh; } /* #endif */ /* #ifdef MP-WEIXIN */ .page { height: calc(100vh - env(safe-area-inset-bottom)); } /* #endif */

写样式条件编译有个很实用的场景：默认样式以H5为准写一份，然后在小程序端单独覆盖。因为小程序的height: 100vh和H5的100vh在处理底部安全区时表现并不一致，与其在运行时算来算去，不如直接编译期各写各的。

模板和样式的条件编译，最常见的问题有两个。一个是模板里漏写<!-- #endif -->，导致后面整段内容都被吞掉，页面渲染直接错乱；另一个是CSS里写了JS风格的行注释//，CSS不认这种东西，自然也不会触发条件编译。这两种错误在HBuilderX的编译日志里不会报得很明显，需要自己对照代码结构去查，所以养成成对书写、写完立即编译验证的习惯很重要。

2.3 pages.json 与 static 目录的平台隔离

pages.json能用的条件编译，我最早也没注意到，后来有一次做“小程序端多一个统计页签”的需求才真正用上。pages.json支持注释和条件编译，比如想让某个页面只在微信小程序端注册：

{ "pages": [ { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } }, // #ifdef MP-WEIXIN { "path": "pages/statistics/statistics", "style": { "navigationBarTitleText": "统计" } } // #endif ] }

注意，pages.json是JSON格式，标准JSON本来不允许写注释，但uni-app对pages.json做了特殊处理，允许注释存在并参与条件编译。懂JSON的人看到这个结构可能会不适应，不过这就是官方设计，放心用即可。同理，tabBar、分包、preloadRule这些配置项也都能用条件编译，解决了跨端项目里一个非常现实的痛点：不同平台对页面数量的要求不一样，有的端审核严格不想要某功能，但你又不想维护两套pages.json，条件编译就是最直接的方案。

manifest.json里同样可以使用条件编译，包括App端的权限声明、第三方SDK配置、H5端的路由模式等。比如App端要声明相机权限，但H5端根本不需要这个权限，这时就可以用条件编译只让App端带上。

static目录本身并不支持条件编译，它里面的文件会被原样打包到所有平台。如果你有“某个静态图片只在微信小程序端展示”，不要把它放在static里，而是放到项目src目录下的其他资源文件夹，比如@/assets/，然后在代码里用条件编译控制引用路径：

// #ifdef MP-WEIXIN import shareIcon from '@/assets/wx-share-icon.png' // #endif // #ifndef MP-WEIXIN import shareIcon from '@/assets/default-share-icon.png' // #endif

这样就能实现资源层面的平台隔离。整体来说，pages.json、manifest.json、资源路径这三块属于条件编译的高阶用法，很多人用了很久都不知道，但它们往往是跨端交付时最有价值的隔离手段。

3. 条件编译实战：三个高频场景的完整拆解

3.1 场景一：平台差异化API封装（登录/支付/分享）

跨端项目里最绕不开的差异就是登录。微信小程序可以用uni.login拿code换openid，App端可能用苹果登录或手机号一键登录，H5端走OAuth跳转。把这三套逻辑写在一个函数里，最暴力的方式是运行时连环if，但代码会非常难看。用条件编译把这层差异收口到单独的API模块里，业务层完全无感，这是我的建议做法：

// utils/login.js export function loginByPlatform() { // #ifdef MP-WEIXIN console.log('小程序端：调用uni.login获取code') return uni.login({ provider: 'weixin' }) // #endif // #ifdef APP-PLUS console.log('App端：调用苹果登录或手机号验证') return new Promise((resolve, reject) => { uni.login({ provider: 'apple', success: (res) => resolve(res), fail: (err) => reject(err) }) }) // #endif // #ifdef H5 console.log('H5端：跳转OAuth授权页') return redirectToOAuth() // #endif }

业务页面在onLoad里直接const res = await loginByPlatform()，完全不用关心当前跑在什么端。后续要接支付宝小程序，只需要在这个文件里加一段MP-ALIPAY的编译块，灰度测试也只在对应平台生效。支付、分享、地图、推送这类平台差异大的能力，都可以用同样的套路封装。

这个模式有个隐藏好处：不同平台的代码不会互相污染。比如App端登录时可能要读设备信息、H5登录要拼接回调地址，这些变量在编译阶段就已经被隔离，不会出现“H5端代码里多了一个App平台对象”这种低级错误。团队协作时也方便，每个人维护自己负责平台的编译块，冲突概率直线下降。

3.2 场景二：H5与小程序环境差异处理

H5和小程序的差异不只是API，还有很多环境层面的隐性差异。最典型的是分享功能：微信小程序有open-type="share"按钮，可以拉起聊天会话中的转发；而H5端Web页面通常需要自己实现一个分享按钮，调用浏览器的分享能力，或者干脆只在页面里显示提示。这时候模板条件编译就派上用场了：

<view class="share-bar"> <!-- #ifdef MP-WEIXIN --> <button open-type="share">微信小程序端分享</button> <!-- #endif --> <!-- #ifdef H5 --> <button @click="handleWebShare">H5端分享</button> <!-- #endif --> </view>

另一个高频差异是baseUrl。H5端因为浏览器跨域限制，接口请求URL往往是绝对路径，小程序则用相对路径或固定域名，App端还会区分测试环境与生产环境的IP。你可以在config文件里统一管理：

// utils/config.js const config = { // #ifdef H5 baseUrl: 'https://web.example.com/api', // #endif // #ifdef MP-WEIXIN baseUrl: 'https://mp.example.com/api', // #endif // #ifdef APP-PLUS baseUrl: 'https://app.example.com/api', // #endif timeout: 15000 } export default config

这里不需要写let baseUrl再在运行时赋值的桥段，直接编译期就定了。注意示例中用了保留域名，实际项目中你按自己的接口环境替换即可。

再说一个容易被忽略的差异：小程序不支持动态document.title，H5可以；小程序底部有tabBar时页面高度天然被压缩，H5没有；小程序里页面栈跳转有层数上限，H5的浏览器历史没有这个限制。这些平台体感层面的差异，都可以通过条件编译在配置、样式、路由三个层面分别处理。

3.3 场景三：同一套代码产出多套定制版本

条件编译不仅能切平台，还能切“业务版本”。一个常见的做法，是用自定义条件编译平台来区分配置不同的客户定制版。比如同一套商城代码，要给三个不同客户交付三套小程序，每套的首页布局、主题色、可见模块都不一样，但共同逻辑占了80%。拆代码库维护三份，代价太高；运行时根据域名或接口返回来判断版本，又要保证所有差异点都有全局状态可读，耦合很重。

用自定义条件编译平台，思路就变成了：同一份源码，打包时针对不同客户定义不同的条件编译标识，需要差异的地方用#ifdef CUSTOMER_A、#ifdef CUSTOMER_B精确控制。HBuilderX里可以通过manifest.json源码视图配置自定义平台，配置持久化后，运行和发行菜单里会多出对应的编译入口，直接一键产出对应定制版。

我实际做过的项目里，这种玩法比预想中稳定。因为条件编译是编译期行为，只要代码里没有把客户标识写错，就不会出现“A客户的版本里残留B客户的功能入口”这类问题。当然，代价是代码里会逐渐增加#ifdef CUSTOMER_X这类业务标识，审查起来需要更细心，但相比维护多套工程，已经算是性价比很高的方案了。具体manifest.json的配置步骤，不同版本HBuilderX略有差异，建议你打开源码视图，看custom节点的代码提示去填写，核心思路就是在某平台节点下注册一个自定义平台名，然后在代码里使用这个名字作为条件编译标识。

4. 常见坑位与排查技巧实录

4.1 条件编译不生效的五个原因

先说结论：条件编译不生效，90%的情况不是框架问题，而是语法写错。我把实际踩过的坑整理成五个高频原因：

1. 注释形式用错。在JS文件里用了/* #ifdef */块注释，或者反过来在CSS文件里用了//行注释。注意各文件的正确注释形式，这是最最常见的低级错误。
2. #endif漏写或位置错。条件编译块必须严格成对，漏一个#endif，后面所有代码都会被编译器当成本平台代码处理，现象就是页面奇奇怪怪地多点东西或少点东西。
3. 平台标识拼写错误或大小写不一致。MP-WEIXIN写成mp-weixin，APP-PLUS写成APP_PLUS，都不会生效。标识符是连字符连接，大小写也要注意。
4. 指令行混在普通代码里。比如const a = 1 // #ifdef H5，这种写法虽然看着像注释，但编译器要求指令独占一行，混写可能不会报错但也不会生效。
5. 手动改过编译配置或缓存残留。改了manifest.json或新增自定义平台后，有时候编译不刷新，需要重新编译或者清一下缓存。用HBuilderX的话，点击菜单里的“重新编译”往往就解决了。

碰到条件编译不生效，我的排查顺序是：先看语法注释形式对不对，再检查成对和拼写，然后清缓存重新编译，最后实在不行就打开当前页面的编译产物，看看那段代码到底有没有进包。把这几步走完，基本能定位问题。

4.2 条件编译与代码规范：这些注释不能乱写

条件编译看着像注释，但本质是编译指令，所以“注释”两个字很容易让人放松警惕。有几条我自己定的规矩，分享给大家：

• 禁止嵌套。#ifdef里面再写一层#ifdef是不被支持的，虽然编译器不一定会报错，但实际行为很难预期，一定要避免。遇到复杂的多平台组合，拆成多个平级编译块处理。
• 指令必须是独立行。不要把条件编译指令和业务代码写在同一行，也不要夹在注释中间。
• 保持成对。写完#ifdef立刻补#endif，不要先写一堆代码再回来补，很容易漏。
• 不要用来临时注释大段代码。有人会把暂时不用的代码用条件编译包起来，假装是“可回滚的注释”。这种做法最大的问题是，一旦#endif拼错，这些代码会比你预想的更“活跃”。想注释代码请用编辑器自带的标准注释，不要用条件编译当注释用。
• 保持平台标识集中管理。如果项目里平台标识散落各处，建议在项目文档里列一个“已用平台标识清单”，新成员进场先看一遍，避免出现#ifdef MP-WEIXIN和#ifdef MP混用的混乱局面。

另外，条件编译块在编辑器里被当成普通注释处理，所以很多开发者会忽略里面的代码质量。里面有死代码、过期变量、不规范命名时，在非本平台编译不会被检查到，等切到那个平台编译时才炸。所以条件编译块内的代码质量同样要接受审查，最好在代码评审流程里单独标注，让评审人能重点看一下平台特有代码。

4.3 排查工具与验证方法

当你怀疑条件编译结果不对的时候，不要靠肉眼猜，直接用工具验证。我常用的验证方式有三种：

第一是看编译产物。HBuilderX编译后，小程序端会生成一个dist目录，你可以在里面搜索#ifdef字符串，如果搜到了，说明条件编译没有生效，代码被当成普通注释或者原样保留下来，这时就去查语法。如果完全搜不到，说明指令已经被正确处理，问题多半出在业务逻辑而不是条件编译本身。

第二是在代码里临时埋点。比如想看这段代码在H5端到底执行了没有，可以在条件编译块内写一句console.log('[条件编译] H5', 1)，然后在编译到H5时看控制台。如果没执行，去检查所在文件有没有被正确加载，或者条件编译块是否包错了位置。这个方法虽然笨，但在定位“某段代码总是出现或总是不出现”时非常直观。

第三是用平台运行模式交叉验证。同一个文件里，分别编译到H5和微信小程序，对比两次产物差异，就能精确知道每个条件编译块到底被裁到哪个平台。这招还能顺便检查条件编译是否误伤了公共代码。我已经养成习惯：每次大规模调整条件编译块之后，都至少交叉编译两个端，确认没有互相污染。

5. 进阶玩法：自定义平台与工程化落地

5.1 自定义条件编译平台解决定制化需求

官方内置的MP-WEIXIN、H5、APP-PLUS标识能覆盖平台差异，但项目一旦进入定制交付阶段，就需要自己的业务标识。举个例子，你有一套商城代码，同时交付给A、B两个客户，各自的小程序账号不一样、首页运营位不一样、主题色不一样。如果只靠运行时读取接口配置来切换，意味着每个用户打开页面都要等配置下发，而且切换逻辑遍布所有页面；用自定义条件编译平台，就能把“A客户专属模块”和“B客户专属模块”在编译期直接隔离。

配置思路是这样的：在manifest.json源码视图里，找到对应平台的节点，新增一个custom节点，保存后HBuilderX会识别出新的自定义平台。之后在代码里就能用新平台名写条件编译，比如// #ifdef CUSTOMER_A。发行时选择对应的自定义平台，产出的包只包含该平台的条件编译分支。这个方案最大的优点是纯粹，编译期就结束了所有差异化，运行时不会多加载任何无效模块。

当然它也有缺点，最大的问题是自定义平台如果做得太多，代码里的条件编译标识会迅速膨胀，维护心智成本上升。我的建议是：自定义平台控制在两到三个以内，超过这个数，就要考虑是不是应该拆成独立工程，或者把差异内容抽成配置化的公共模块，而不是继续往条件编译里堆。

5.2 条件编译在团队协作中的约定

条件编译用好了是神器，用乱了就是灾难。团队协作时，我强烈建议在项目规范里写清楚下面几点：

第一，建立“跨端差异清单”。每一位开发者遇到平台差异，先想清楚能不能用框架自带能力解决，解决不了再上条件编译。记录到清单里，注明差异点、涉及文件、使用标识，避免后面人重复踩坑。

第二，评审时重点检查条件编译块。条件编译块里的代码不参与当前平台编译，所以常规测试覆盖不到。代码评审时要把平台特有代码单独拎出来看，有条件的话，每个平台的编译产物都跑一遍冒烟测试。

第三，统一错误处理。有些平台特有API在非本平台根本不存在，如果条件编译块里没有写错误兜底，切平台编译时就会暴露。建议约定平台特有代码必须处理失败分支，保证其他平台即使数据结构不同，也不会因缺字段直接崩掉。

第四，沉淀公共封装。多个页面都用到了“微信小程序分享”，那就不要把条件编译写到每个页面的template里，而是封装成组件或mixins，页面层只暴露一个share()方法。这样即使后续平台增加，也只改封装处，业务层完全不受影响。

上述约定看起来简单，但真能执行下去，项目条件编译的维护成本会低很多。我见过不少项目，代码里#ifdef满天飞，问起来谁都不知道某个标识对应什么需求，最后只能靠版本管理工具一条条往回查，相当痛苦。

5.3 uni_modules与条件编译的配合

如果你开发过适用于uni-app的插件或组件，并且放到uni_modules生态中，条件编译几乎是绕不开的。插件要适配多端，最好的方式就是内部使用条件编译处理平台差异，对外暴露统一的接口，让使用方无感知。

比如我写过一个小工具组件，内部用到了剪贴板。H5端的剪贴板API和小程序端的uni.setClipboardData行为不一样，组件内部就用条件编译分开处理，对页面使用者来说只看到一个copy(text)方法。这样插件在不同平台的表现一致，维护也容易。

在uni_modules里用条件编译，还要注意插件的文档建设。因为插件使用者可能不在你的团队里，不清楚哪个平台走了哪段逻辑，所以插件文档里应该明确标注“当前版本在微信小程序端如何处理、在App端如何处理”，有条件的话给出完整平台测试矩阵。另一个细节是，uni_modules插件的JS代码里用条件编译时，注释格式依然要遵循各文件的语言规范，这一点跟普通业务代码没有区别。

说实话，uni_modules配合条件编译，本质上还是编译期隔离，只是多了一层“插件封装”的表皮。它的好处是让平台差异对使用方透明化，让跨端组件真正做到“一次编写，多端可用”。如果你正打算发布自己的uni_modules组件，条件编译这块值得花点心思设计，因为它直接决定插件能覆盖多少端、维护成本有多高。

我个人用条件编译这几年，最大的体会是：它确实是跨端开发里最值得优先掌握的编译期能力，但用的时候一定要克制。平台差异能交给公共API或配置解决的，就不要堆条件编译；一旦用了，注释成对、标识清晰、封装到位这三条底线必须守住。很多新人在接触条件编译时，容易把它当成万能解药，什么都往里塞，结果代码里到处是平台分支，最后比不用还难受。如果你现在正被平台差异折磨，建议你先从封装一个登录模块开始，把H5、微信小程序、App三种实现各写一段条件编译，再编译几个端看看产物变化。跑通这个体验闭环，你对条件编译的理解会比看十篇文档都深刻。后续遇到新的平台差异，你也会很自然地想到先去查它到底是编译期该管的事，还是运行时该管的事。