企业官网建设流程全解析

跨端开发里最让人头疼的，往往不是写业务代码，而是"一套代码跑在多个宿主环境"这件事。uni-app 把微信、支付宝、H5、App 都覆盖得不错，但一提到钉钉小程序，很多人的第一反应是"能跑吗、坑多不多"。我最近刚好把一个内部工具从微信小程序迁到钉钉小程序上，中间踩了不少编译、API 差异、登录鉴权、样式适配的坑，索性把整个过程梳理成一篇可复现的实操记录。这篇内容适合已经会用 uni-app 写基础页面、但没接触过钉钉端的开发者，也适合正在评估"要不要把现有小程序迁到钉钉"的技术负责人。核心关键词就三个：uni-app 多端适配、钉钉小程序、条件编译。读完你至少能做到：项目能编译进钉钉、登录链路能跑通、常见样式和 API 差异心里有数。

1. 先搞清楚钉钉小程序到底是不是"又一个微信小程序"

动手之前必须先建立一个正确认知：钉钉小程序在技术底座上确实和微信小程序高度相似，都是类小程序的双线程架构、都有独立的 IDE、都走自己的 JSAPI 体系，但它们在运行时能力、鉴权模型、开放接口命名上有实打实的差异。如果你抱着"改个 appid 就能跑"的心态进去，大概率会在登录和网络请求这两块卡住。

1.1 底座相似但能力边界不同

从 uni-app 的编译目标来看，钉钉小程序走的是mp-dingtalk这个平台标识，编译产物结构和微信小程序（mp-weixin）非常接近，都是app.json+ 页面目录 + 分包的结构。这意味着 uni-app 的组件体系、生命周期、数据绑定在钉钉端基本能复用，页面渲染层不需要大改。

但相似不等于相同。钉钉的宿主环境更偏"企业办公"场景，它把大量能力围绕组织架构、审批、消息、通讯录来设计，而微信更偏"社交 + 支付"。这直接导致两边的开放接口集合不一样：微信有wx.login、wx.requestPayment，钉钉对应的是dd.getAuthCode、dd.pay这类。你在 uni-app 里写uni.login()，在微信端它会映射到wx.login，在钉钉端映射到钉钉的授权接口，但映射不是 100% 覆盖，有些接口钉钉端根本没有对应实现，调用会直接失败或返回 undefined。

我的建议是：迁移前先列一张"项目用到的 uni API 清单"，逐个对照 uni-app 官方文档里各端的兼容性表格，把钉钉端不支持的标红。这一步花半小时，能省掉后面几天的调试。

1.2 为什么不能直接复用微信的登录逻辑

这是最容易翻车的地方。微信小程序的登录是"wx.login拿 code → 后端换 openid/session_key → 自定义登录态"，钉钉的登录模型完全不同：它基于企业内的免登（authCode）和扫码/账号授权两套体系。钉钉小程序里最常用的是dd.getAuthCode，拿到的是临时授权码，后端要用它去换用户的 userId 和企业信息，而且这套流程强依赖企业在钉钉开放平台配置的应用凭证。

换句话说，微信那套"code 换 session"的思路在钉钉上要重新设计。你不能指望uni.login()一把梭，得针对钉钉端单独写登录分支。这也是为什么下面要重点讲条件编译——它是 uni-app 处理这种平台差异的标准手段。

1.3 迁移前必须确认的三件事

在正式动手前，我建议先确认三件事，缺一件都会导致后面返工：

• 企业是否已开通钉钉开放平台应用：需要拿到应用的 AppKey / AppSecret，并在应用里配置小程序的合法域名、回调地址。没有这个，登录和网络请求都跑不通。
• 目标用户是否都在同一组织内：钉钉小程序的免登依赖组织身份，如果用户是外部人员，得走另一套授权流程，复杂度完全不同。
• 现有项目是否重度依赖微信特有能力：比如微信支付、微信卡券、微信运动等，这些在钉钉端没有等价物，需要产品层面决定是砍掉还是替换。

把这三件事确认清楚，再进入环境配置环节，心态会稳很多。

2. 环境配置：从 HBuilderX 到钉钉开发者工具的完整链路

uni-app 编译到钉钉小程序，本质是"用 HBuilderX（或 CLI）把源码编译成钉钉能识别的产物，再用钉钉开发者工具打开这个产物目录"。这条链路里有两个工具、一个平台标识、一个 appid，任何一环配错都编译不进去。

2.1 编译平台标识与 manifest 配置

第一步是在manifest.json里补上钉钉小程序的配置节点。uni-app 用mp-dingtalk作为钉钉端的平台标识，配置结构和小程序通用字段类似：

{ "mp-dingtalk": { "appid": "你的钉钉小程序appid", "setting": { "urlCheck": false, "es6": true, "minified": true }, "usingComponents": true } }

这里的appid不是微信的 appid，而是钉钉开放平台里创建小程序应用后分配的那个标识。urlCheck: false在开发阶段建议打开（即关闭域名校验），否则本地调试时请求没配白名单的接口会直接被拦。上线前记得改回true并配好合法域名。

如果你用的是 HBuilderX 图形界面，可以在manifest.json的可视化编辑器里找到"钉钉小程序配置"这一栏，填 appid 即可，效果和手写 JSON 一样。我个人的习惯是手写，因为可视化编辑器偶尔会覆盖掉自定义字段。

2.2 编译命令与产物目录

用 CLI 的话，编译命令是：

# 开发模式，带 sourcemap，产物在 dist/dev/mp-dingtalk npm run dev:mp-dingtalk # 生产模式，产物在 dist/build/mp-dingtalk npm run build:mp-dingtalk

这两个脚本需要在package.json里预先定义好，如果你是从老项目迁过来的，很可能只有dev:mp-weixin，得手动补上钉钉的脚本。补的时候注意命令名要和 uni-app 的约定一致，否则编译会报"未知平台"。

编译完成后，产物目录dist/dev/mp-dingtalk就是钉钉开发者工具要打开的根目录。这里有个细节：不要用 HBuilderX 的"运行到小程序模拟器"直接选钉钉，某些版本对钉钉的支持不完整，最稳的方式是"发行/运行 → 生成产物 → 手动用钉钉开发者工具打开产物目录"。

2.3 钉钉开发者工具的导入与调试

打开钉钉开发者工具，选择"导入项目"，目录指向刚才的dist/dev/mp-dingtalk，工具会自动读取里面的app.json和project.config.json。如果导入时报"appid 不匹配"，八成是manifest.json里的 appid 和工具里登录的账号所属组织对不上，检查一下当前登录的钉钉账号是不是目标企业的成员。

调试面板和微信开发者工具很像，有 Console、Network、Storage、元素审查。但钉钉工具的 Network 面板对请求的展示粒度略粗，有时候看不到完整的响应体，这时候我会在代码里临时加console.log打印响应，比在面板里翻更直接。

提示：钉钉开发者工具对 Node 版本有要求，太新的 Node 可能导致工具启动失败。我实测 Node 16 和 18 比较稳，20 以上偶发白屏，遇到工具打不开先降 Node 版本试试。

3. 条件编译：让同一份代码在钉钉端走不同分支

条件编译是 uni-app 处理多端差异的核心武器，语法是用特殊注释包裹代码块，编译时只保留目标平台的代码。钉钉端的平台标识在条件编译里写作MP-DINGTALK，注意是全大写、带连字符。

3.1 条件编译的基本语法与钉钉标识

// #ifdef MP-DINGTALK console.log('这段代码只在钉钉小程序里编译'); // #endif // #ifndef MP-DINGTALK console.log('这段代码在除钉钉外的所有平台编译'); // #endif

#ifdef是"如果定义了某平台"，#ifndef是"如果没定义某平台"。除了钉钉，常用的还有MP-WEIXIN、MP-ALIPAY、H5、APP-PLUS。多个平台可以用||连接，比如#ifdef MP-DINGTALK || MP-WEIXIN。

这里有个新手常犯的错：把条件编译注释写在.vue的<template>里时，注释符号要用 HTML 注释风格<!-- #ifdef MP-DINGTALK -->，写在<script>和<style>里才用//或/* */。写错位置编译器不会报错，但代码不会被正确剔除，最后打包体积莫名变大还找不到原因。

3.2 登录逻辑的分平台实现

这是条件编译最典型的应用场景。假设项目里有一个统一的登录方法，微信端走uni.login，钉钉端走dd.getAuthCode：

function login() { // #ifdef MP-WEIXIN return new Promise((resolve, reject) => { uni.login({ provider: 'weixin', success: (res) => resolve(res.code), fail: reject }); }); // #endif // #ifdef MP-DINGTALK return new Promise((resolve, reject) => { dd.getAuthCode({ success: (res) => resolve(res.authCode), fail: reject }); }); // #endif }

注意钉钉端这里直接调用了全局的dd对象，这是钉钉小程序的宿主 API 命名空间，和微信的wx对应。在 uni-app 里，钉钉端可以直接用dd，不需要额外引入。但如果你在 H5 或微信端也写了dd.xxx而没加条件编译，编译到那些平台时会报dd is not defined，所以务必用#ifdef包住。

拿到 authCode 之后，后端要用它去钉钉开放平台换用户信息，这一步是服务端的事，前端只负责把 authCode 传过去。整个链路是：前端dd.getAuthCode→ 后端调钉钉接口换 userId → 后端签发自己的 token → 前端存 token。和微信的 code 换 session 思路一致，只是换的接口和凭证不同。

3.3 样式与组件的分平台处理

样式差异相对少，但也不是没有。钉钉小程序的默认字体、部分内置组件的默认样式和微信有细微差别，比如button的默认高度、picker的弹层样式。如果设计稿对像素级还原要求高，建议在<style>里用条件编译微调：

/* #ifdef MP-DINGTALK */ .dingtalk-btn { height: 88rpx; line-height: 88rpx; } /* #endif */

组件层面，如果项目里用了某些只在微信端支持的第三方组件库，钉钉端要么换库、要么用条件编译替换成原生实现。我的做法是抽象一层"平台适配组件"，对外暴露统一 props，内部用条件编译决定渲染哪个实现，业务页面不感知差异。

4. 踩坑实录：钉钉端最容易翻车的四类问题

前面讲的是"应该怎么做"，这一节讲"实际做的时候会怎么坏"。这些问题我在迁移过程中几乎全踩了一遍，按出现频率从高到低排列。

4.1 网络请求的域名白名单与跨域

钉钉小程序和微信一样，请求必须走白名单域名，而且必须是 HTTPS。开发阶段可以在开发者工具里勾选"不校验合法域名"，但真机预览和上线后这个开关无效，请求会被直接拦截，报错信息还很含糊，只提示"请求失败"。

排查这类问题的完整链路是这样的：先在开发者工具 Network 面板确认请求有没有发出去；如果没发出去，检查域名是否在钉钉开放平台的应用配置里加了白名单；如果发出去了但失败，看响应头是不是缺 CORS 相关字段（钉钉小程序虽然不走浏览器同源策略，但服务端如果做了严格的 Origin 校验也会拦）。我遇到过一次是后端网关对 User-Agent 做了限制，钉钉小程序的 UA 和微信不同，被网关挡了，这种问题只能靠抓包定位。

注意：钉钉开放平台配置合法域名后，生效有延迟，通常几分钟到十几分钟不等。改完别急着测，等一会儿再试，否则会误判成配置没生效。

4.2 登录态失效与静默续期

钉钉的 authCode 是一次性的，用过即失效，而且有效期很短。如果你的登录逻辑是"进页面拿一次 authCode 就一直用"，那用户切后台再回来、或者 token 过期后重新请求，就会失败。正确做法是把 authCode 只用于"换取后端 token"这一步，后续所有请求都带后端签发的 token，token 快过期时用 refresh token 续期，而不是反复调dd.getAuthCode。

我一开始没注意这点，写了个"每次请求前都调 getAuthCode"的逻辑，结果钉钉端频繁报授权失败，因为 authCode 被重复消费了。改成"首次登录换 token，后续用 token"之后问题消失。这个坑在微信端不明显，因为微信的 code 虽然也是一次性，但很多项目用了checkSession做静默续期，钉钉端没有完全等价的机制，得自己设计。

4.3 页面栈与返回行为的差异

钉钉小程序的页面栈上限和微信一样是 10 层，但navigateBack的行为在个别版本上有差异：微信端navigateBack到不存在的层级会静默失败，钉钉端某些版本会直接报错。如果你的代码里有"返回到指定页、失败则 reLaunch"的兜底逻辑，在钉钉端要把 try-catch 加上，避免报错中断后续逻辑。

另外，钉钉的"返回"物理行为（安卓端侧滑、顶部返回按钮）和微信略有不同，尤其是从钉钉工作台进入小程序再返回时，可能直接回到工作台而不是上一页。涉及多步表单的场景，建议用redirectTo或本地缓存保存草稿，别完全依赖页面栈。

4.4 本地存储的容量与序列化

uni.setStorageSync在钉钉端的底层实现和微信不同，容量上限和序列化行为有细微差别。我遇到过一次存了一个较大的 JSON 对象（约 800KB），微信端正常，钉钉端写入成功但读出来是[object Object]字符串，原因是钉钉端对非字符串类型做了隐式toString。解决办法是存之前手动JSON.stringify，读之后JSON.parse，不要依赖框架的自动序列化。

容量方面，钉钉小程序单个 key 的上限比微信略小，大对象建议拆分存储或改用后端缓存。这个差异官方文档写得比较隐晦，是我实际测出来的。

5. 上线前的自查清单与真机验证方法

代码能跑通只是第一步，真正决定能不能上线的是真机表现和配置完整性。这一节给一份我实际用过的自查清单，以及真机验证的具体操作方法。

5.1 配置项逐条核对

上线前把下面这张表过一遍，每一条都对应一个曾经让我返工的点：

这张表看着简单，但每一条我都至少踩过一次。尤其是 appid 填错这一条，编译阶段完全不报错，只有真机打开才白屏，排查起来很费时间。

5.2 真机预览与日志抓取

钉钉开发者工具的"预览"会生成一个二维码，用钉钉扫码即可在真机打开。真机上的 console 日志不会自动同步到工具里，需要开启"真机调试"模式，工具会通过长连接把日志回传。如果真机调试连不上，检查手机和电脑是否在同一网络、钉钉版本是否过旧。

真机验证重点看三件事：登录能不能走通、首屏加载时间是否可接受、关键交互（表单提交、列表滚动）是否卡顿。钉钉小程序的冷启动比微信略慢，如果首屏有大量同步请求，建议改成并行或延迟加载。

5.3 灰度与回滚策略

钉钉小程序支持版本管理和灰度发布，上线时不要一次性全量。先在开放平台把新版本设为"灰度"，指定少量用户或部门试用，观察一两天没有异常再全量。回滚也很简单，把线上版本切回上一个即可，但要注意后端接口要兼容新旧两个前端版本，否则回滚后老版本调新接口会挂。

我在实际项目里的做法是：前端版本号和后端接口版本号解耦，接口只做加法不做破坏性修改，这样灰度期间新旧前端共存也不会出问题。

6. 一些不那么"文档化"的经验

最后分享几个官方文档里不会写、但实际很影响效率的点。

第一，钉钉开发者工具的缓存很顽固。改了代码重新编译，工具里有时还是旧页面，清缓存要清好几层（工具缓存 + 小程序本地缓存 + 真机缓存）。我的习惯是每次大改后手动点"清缓存 → 全部清除"，再重新编译，比反复怀疑代码写错高效得多。

第二，条件编译的代码块不要嵌套太深。我见过有人在#ifdef里再套#ifdef，编译结果完全不可预期。平台差异尽量在方法级别隔离，一个方法只处理一个平台的逻辑，别在一个函数里堆四五层条件编译。

第三，钉钉端的 API 报错信息普遍比微信简略。微信报错会告诉你哪个参数错了，钉钉经常只给一个错误码。建议在封装dd.xxx调用时统一加错误码映射表，把常见错误码翻译成人话，调试时能省很多查文档的时间。

第四，别忽视钉钉的"组织身份"这个前提。很多在微信端理所当然的"匿名可用"功能，在钉钉端因为强依赖组织身份，未登录状态下根本调不通。产品设计阶段就要想清楚哪些功能需要登录、哪些可以游客访问，别等开发完了才发现逻辑走不通。

这套迁移流程走下来，一个中等复杂度的小程序大概需要三到五天，其中登录和网络请求占大头，样式适配反而最快。如果你的项目刚起步、还没重度绑定微信特有能力，现在就把钉钉端纳入编译目标、用条件编译隔离平台差异，后续迁移成本会低很多。