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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，登录后在控制台里找到 API Keys 页面，新建一个 Key 并复制保存。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Keys 管理页是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

如果你只是想先验证模型能不能通，用模型对话页面最快：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。想长期做编码任务、跑 Agent，就看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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 class="form-wrap"> <input v-model="inputValue" type="text" placeholder="请输入内容" cursor-spacing="85" :always-embed="true" :adjust-position="false" @focus="onFocus" @blur="onBlur" /> </view> </template>

逐个解释这三个属性：

cursor-spacing="85"指定光标与键盘的距离，单位是 px。官方文档说取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离。注意单位是 px 不是 rpx，85px 在大部分 iPhone 上大约对应键盘上方留出一指宽。如果你原来写的是85rpx，在 iOS 上换算后只有 40 多 px，距离不够，还是会偶发被盖住。这是很多人踩的坑：rpx 在 iOS 上换算比例跟设计稿宽度有关，键盘距离这种跟物理尺寸相关的参数，用 px 更稳。

:always-embed="true"强制 input 处于同层状态。默认 focus 时 input 会切到非同层状态，这个属性仅在 iOS 下生效。同层状态下，input 就是普通文档流里的元素，页面滚动、定位都正常，不会出现原生控件脱离文档流导致的错位。这是解决"挤上去"的根本。

:adjust-position="false"关闭页面自动上推。默认值是 true，键盘弹出时页面会自动往上顶。关掉它之后，页面不动，靠 cursor-spacing 让系统把输入框滚到可视区。这两个要配合用：如果 adjust-position 还是 true，页面会先被顶一次，再被 cursor-spacing 调整一次，就会出现"跳一下"的观感。

如果你的 input 在 u-popup 弹窗里，弹窗本身还有一层定位，配置要再补一点：

<u-popup :show="showPopup" mode="bottom" :safeAreaInsetBottom="true"> <view class="popup-content"> <input v-model="inputValue" cursor-spacing="85" :always-embed="true" :adjust-position="false" :hold-keyboard="true" @focus="onFocus" /> </view> </u-popup>

:hold-keyboard="true"是让点击弹窗内其他元素时键盘不收起，避免输入过程中键盘反复弹收导致的页面抖动。:safeAreaInsetBottom="true"让弹窗底部避开 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-embed="true"。这是个高频错误：always-embed="true"传的是字符串，:always-embed="true"传的才是布尔值。

第四步，验证输入框位置。在 input 聚焦状态下，用uni.createSelectorQuery拿输入框的 boundingClientRect：

const 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-spacing="85"和always-embed之后，iPhone 12 到 iPhone 15 全系都能稳定通过，输入框停在键盘上方约 85px 的位置。

第五步，测试边界场景：连续快速点击 input 聚焦失焦、在弹窗里输入后滚动页面、切换输入法（中文/英文/emoji）。这几个场景最容易暴露偶发问题。如果都稳定，说明配置到位了。

5. 本篇常见错误排查对照

这一节列真实会遇到的报错和现象，对照排查。

现象一：always-embed写了但没生效，输入框还是被顶。检查写法。always-embed="true"是字符串，:always-embed="true"才是布尔。在 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/api，Key 填 API Key，Model ID 填对应模型。三件套缺一不可。

现象五：输入框在弹窗里位置对，但页面滚动后错位。这是adjust-position和cursor-spacing冲突。确认:adjust-position="false"已经加上，并且弹窗用了safeAreaInsetBottom。

现象六：安卓端正常，iOS 端偶发。偶发通常是键盘动画还没结束就触发了滚动。可以在@focus里加一个 300ms 的延时再执行定位逻辑，等键盘动画完成。

对照表：

排障时如果拿不准，把报错原文贴到模型对话页面让模型帮你分析，比搜索引擎翻半天快。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Keys 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

6. 把配置沉淀成团队规范

最后说点实操经验。iOS 键盘问题之所以烦，是因为它跟机型、系统版本、小程序基础库版本都耦合，今天修好了明天换个机型又冒出来。所以别只改一个页面，把配置沉淀成团队规范。

建议在项目里建一个统一的 input 封装组件，把cursor-spacing、always-embed、adjust-position三个属性写死在里面，所有页面都用这个组件。这样新同学不会漏配，老页面迁移也有统一入口。封装大概长这样：

<template> <input :value="value" :cursor-spacing="cursorSpacing" :always-embed="true" :adjust-position="false" :hold-keyboard="holdKeyboard" @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 } } } </script>

cursor-spacing默认给 85px，特殊场景可以传参覆盖。always-embed和adjust-position直接写死，不给外部改的机会，避免有人手滑改回去。

另外，把 iOS 真机验证加进提测清单。每次发版前，至少在 iPhone 上跑一遍表单页的聚焦、输入、失焦、滚动四个动作。这个成本很低，但能挡住大部分键盘回归问题。

如果你团队里同时在跑多个模型相关的调试任务，用 TaoToken 的 Coding Plan 可以把这些排查工作串起来，一个 Key 管住对话和编码两条线，省得每个人维护自己的 Key。长期编码和 Agent 场景看 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

配置改完记得清一次小程序缓存再真机预览，有时候旧配置会残留在本地。这个坑我踩过，改了代码没生效，折腾半天才发现是缓存。