1. iOS 真机上 input 被软键盘顶飞的现场还原先说清楚这篇要解决的是什么问题uni-app 打包成小程序微信/支付宝等后在 iOS 真机上点击 input 输入框页面整体被软键盘往上顶输入框跑到屏幕外或者被键盘盖住用户根本看不到自己输入的内容。安卓端通常没事iOS 端必现或者偶发。适合谁看正在用 uni-app 写表单、弹窗输入、聊天输入框并且被 iOS 键盘顶起问题折磨的前端同学。我试过最原始的做法是判断机型然后动态加高度。思路很直白iOS 就把 input 父容器撑高一点让输入框离键盘远一些。代码大概长这样const info wx.getSystemInfoSync() if (info.system.indexOf(Android) -1) { console.log(安卓) } else { this.Bottom 235 console.log(ios) }然后给父元素动态绑定高度。结果确实能解决但代价是弹窗底部留出一大块空白视觉上很丑而且不同机型键盘高度不一样写死的 235 在 iPhone SE 和 iPhone 15 Pro Max 上表现完全不同。后来又尝试在 focus/blur 事件里做动画让弹窗跟着键盘滑动结果就是输入框跳一下体验更差。问题的根子在于iOS 下 input 聚焦时默认会切到非同层状态WebView 的原生输入控件会脱离文档流单独渲染这时候页面滚动、定位、层级全都乱套。你调父容器高度只是在跟这个机制对抗而不是顺应它。真正干净的解法是让 input 始终处于同层状态再配合光标与键盘的距离参数让系统自己把输入框放到可视区里。这篇会从三条线拆cursor-spacing控制光标与键盘距离、adjust-position控制页面是否自动上推、键盘高度监听做兜底。三条线配合才能让输入框稳定停在可视区。下面给出可以直接复制的pages.json和 input 组件配置以及 iOS 真机验证步骤。2. TaoToken 统一 Key 前置把模型能力接进你的调试链路在动手改配置之前先把调试链路搭好。很多同学排查 iOS 键盘问题时靠的是反复真机预览 肉眼观察效率很低。更聪明的做法是接一个统一的模型入口让 AI 帮你读报错、分析配置、生成对照代码。这里用 TaoToken 做统一 Key 管理一个 Key 走通对话、编码、Agent 几条线省得在多个平台之间来回切。TaoToken 是什么一个统一的大模型 API 入口兼容 OpenAI 风格的接口协议提供模型对话、Coding Plan、控制台和 API Keys 管理。能做什么你可以用它跑模型对话验证接口通不通也可以用 Coding Plan 做长期编码任务还能在控制台里管理多个 Key 的额度。适合谁需要在一个项目里同时调多个模型、又不想维护一堆 Key 的开发者。接入前你需要准备三样东西这三件套在任何客户端里都一样Base URL、API Key、Model ID。Base URL 填https://taotoken.net/api注意这个地址不带任何查询参数。API Key 去控制台生成Model ID 按你实际要用的模型填。具体操作路径先去官网注册并登录地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后在控制台里找到 API Keys 页面新建一个 Key 并复制保存。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Keys 管理页是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你只是想先验证模型能不能通用模型对话页面最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想长期做编码任务、跑 Agent就看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。为什么排查 iOS 键盘问题要接这个因为你可以把真机上的报错日志、pages.json片段、input 组件代码一起丢给模型让它帮你比对官方文档里cursor-spacing和always-embed的行为差异。尤其是always-embed这个属性官方文档写得很简略实际表现跟机型、系统版本、小程序基础库版本都有关有个能对话的模型帮你逐条分析比你自己翻论坛快得多。这里要提醒一句TaoToken 是 API 入口不是编辑器替代品你的代码还是在 HBuilderX 或 VS Code 里写它只负责提供模型能力。另外不要把生产数据库直连到任何 MCP 工具上调试用的 Key 和生产的 Key 要分开管理。3. 可复制的 pages.json 与 input 组件配置片段这一节是核心直接给能跑的配置。先看pages.json里跟键盘相关的全局配置。uni-app 在小程序端有一个app-plus之外的配置项针对微信小程序可以在pages.json的页面 style 里设置adjustPosition但更推荐在 input 组件上单独控制粒度更细。先给pages.json的页面级配置{ pages: [ { path: pages/form/index, style: { navigationBarTitleText: 表单页, app-plus: { softinputMode: adjustResize } } } ], globalStyle: { navigationBarTextStyle: black, navigationBarBackgroundColor: #FFFFFF } }softinputMode设成adjustResize是让页面在键盘弹出时重新计算可视区高度而不是整体上推。这个配置在 App 端生效小程序端主要靠组件属性。接下来是 input 组件的关键配置。这是解决 iOS 顶起问题的两行核心template view classform-wrap input v-modelinputValue typetext placeholder请输入内容 cursor-spacing85 :always-embedtrue :adjust-positionfalse focusonFocus bluronBlur / /view /template逐个解释这三个属性cursor-spacing85指定光标与键盘的距离单位是 px。官方文档说取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离。注意单位是 px 不是 rpx85px 在大部分 iPhone 上大约对应键盘上方留出一指宽。如果你原来写的是85rpx在 iOS 上换算后只有 40 多 px距离不够还是会偶发被盖住。这是很多人踩的坑rpx 在 iOS 上换算比例跟设计稿宽度有关键盘距离这种跟物理尺寸相关的参数用 px 更稳。:always-embedtrue强制 input 处于同层状态。默认 focus 时 input 会切到非同层状态这个属性仅在 iOS 下生效。同层状态下input 就是普通文档流里的元素页面滚动、定位都正常不会出现原生控件脱离文档流导致的错位。这是解决挤上去的根本。:adjust-positionfalse关闭页面自动上推。默认值是 true键盘弹出时页面会自动往上顶。关掉它之后页面不动靠 cursor-spacing 让系统把输入框滚到可视区。这两个要配合用如果 adjust-position 还是 true页面会先被顶一次再被 cursor-spacing 调整一次就会出现跳一下的观感。如果你的 input 在 u-popup 弹窗里弹窗本身还有一层定位配置要再补一点u-popup :showshowPopup modebottom :safeAreaInsetBottomtrue view classpopup-content input v-modelinputValue cursor-spacing85 :always-embedtrue :adjust-positionfalse :hold-keyboardtrue focusonFocus / /view /u-popup:hold-keyboardtrue是让点击弹窗内其他元素时键盘不收起避免输入过程中键盘反复弹收导致的页面抖动。:safeAreaInsetBottomtrue让弹窗底部避开 iPhone 的 Home Indicator 区域。再给一个键盘高度监听的兜底方案放在页面的 script 里export default { data() { return { inputValue: , keyboardHeight: 0 } }, methods: { onFocus(e) { const { height } e.detail this.keyboardHeight height || 0 console.log(键盘高度:, this.keyboardHeight) }, onBlur() { this.keyboardHeight 0 } } }focus事件的e.detail.height在 iOS 上能拿到键盘高度你可以用它做动态布局比如把输入框往上顶keyboardHeight的距离。但注意有了always-embed和cursor-spacing之后大部分场景不需要再手动算高度这个监听只作为极端机型的兜底。4. iOS 真机验证请求与成功结果配置改完必须上真机验证模拟器不准。下面是完整验证步骤。第一步用 HBuilderX 运行到微信小程序然后点预览用 iPhone 扫码打开。别用开发者工具的模拟器iOS 键盘行为模拟器复现不出来。第二步进入表单页点击 input 聚焦。观察三件事页面有没有整体上推、输入框是不是停在键盘上方可见、光标位置是不是在输入框内正常闪烁。第三步打开微信开发者工具的 vConsole或者在小程序里用console.log输出。聚焦时看控制台有没有打印键盘高度onFocus(e) { console.log(focus detail:, JSON.stringify(e.detail)) }正常输出类似{value:,height:336,duration:300}height: 336就是当前键盘高度单位 px。如果height是 0 或者 undefined说明always-embed没生效检查属性是不是写成了字符串true而不是布尔:always-embedtrue。这是个高频错误always-embedtrue传的是字符串:always-embedtrue传的才是布尔值。第四步验证输入框位置。在 input 聚焦状态下用uni.createSelectorQuery拿输入框的 boundingClientRectconst query uni.createSelectorQuery().in(this) query.select(.form-wrap input).boundingClientRect(rect { console.log(输入框位置:, rect.top, rect.bottom) const screenHeight uni.getSystemInfoSync().windowHeight console.log(可视区高度:, screenHeight) if (rect.bottom screenHeight - 336) { console.log(输入框在键盘上方OK) } else { console.log(输入框被键盘遮挡需要调整) } }).exec()成功的结果是rect.bottom小于windowHeight - keyboardHeight也就是输入框底边在键盘顶边之上。实测下来配上cursor-spacing85和always-embed之后iPhone 12 到 iPhone 15 全系都能稳定通过输入框停在键盘上方约 85px 的位置。第五步测试边界场景连续快速点击 input 聚焦失焦、在弹窗里输入后滚动页面、切换输入法中文/英文/emoji。这几个场景最容易暴露偶发问题。如果都稳定说明配置到位了。5. 本篇常见错误排查对照这一节列真实会遇到的报错和现象对照排查。现象一always-embed写了但没生效输入框还是被顶。检查写法。always-embedtrue是字符串:always-embedtrue才是布尔。在 uni-app 的 template 里不带冒号的属性传的是字符串带冒号的才是表达式。这个错误极其常见我见过好几个同学卡在这里。现象二控制台报local proxy failed或请求超时。这通常跟键盘问题无关是你接模型 API 时 Base URL 配错了。检查是不是把https://taotoken.net/api写成了带路径的地址或者 Key 复制时多了空格。401 报错就是 Key 无效或没带Authorization头格式是Bearer 你的Key。现象三reading choices报错。这是解析模型返回时字段对不上通常是请求体里model字段填的 Model ID 跟实际可用模型不匹配。去模型对话页面确认一下当前可用的 Model ID再填回配置。现象四OAuth 相关报错。如果你用的是 Claude Code 或类似客户端认证方式可能走 OAuth 而不是 API Key。这时候要确认客户端配置里的认证模式Base URL 填https://taotoken.net/apiKey 填 API KeyModel ID 填对应模型。三件套缺一不可。现象五输入框在弹窗里位置对但页面滚动后错位。这是adjust-position和cursor-spacing冲突。确认:adjust-positionfalse已经加上并且弹窗用了safeAreaInsetBottom。现象六安卓端正常iOS 端偶发。偶发通常是键盘动画还没结束就触发了滚动。可以在focus里加一个 300ms 的延时再执行定位逻辑等键盘动画完成。对照表现象可能原因处理输入框被顶飞always-embed 写法错误改成:always-embedtrue键盘距离不够cursor-spacing 用了 rpx改成 px 单位页面跳一下adjust-position 没关加:adjust-positionfalse401Key 无效或格式错检查Bearer前缀reading choicesModel ID 不匹配核对可用模型列表OAuth 报错认证模式不对确认客户端认证方式排障时如果拿不准把报错原文贴到模型对话页面让模型帮你分析比搜索引擎翻半天快。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。6. 把配置沉淀成团队规范最后说点实操经验。iOS 键盘问题之所以烦是因为它跟机型、系统版本、小程序基础库版本都耦合今天修好了明天换个机型又冒出来。所以别只改一个页面把配置沉淀成团队规范。建议在项目里建一个统一的 input 封装组件把cursor-spacing、always-embed、adjust-position三个属性写死在里面所有页面都用这个组件。这样新同学不会漏配老页面迁移也有统一入口。封装大概长这样template input :valuevalue :cursor-spacingcursorSpacing :always-embedtrue :adjust-positionfalse :hold-keyboardholdKeyboard input$emit(input, $event.detail.value) focus$emit(focus, $event) blur$emit(blur, $event) / /template script export default { name: SafeInput, props: { value: { type: String, default: }, cursorSpacing: { type: Number, default: 85 }, holdKeyboard: { type: Boolean, default: true } } } /scriptcursor-spacing默认给 85px特殊场景可以传参覆盖。always-embed和adjust-position直接写死不给外部改的机会避免有人手滑改回去。另外把 iOS 真机验证加进提测清单。每次发版前至少在 iPhone 上跑一遍表单页的聚焦、输入、失焦、滚动四个动作。这个成本很低但能挡住大部分键盘回归问题。如果你团队里同时在跑多个模型相关的调试任务用 TaoToken 的 Coding Plan 可以把这些排查工作串起来一个 Key 管住对话和编码两条线省得每个人维护自己的 Key。长期编码和 Agent 场景看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配置改完记得清一次小程序缓存再真机预览有时候旧配置会残留在本地。这个坑我踩过改了代码没生效折腾半天才发现是缓存。