小程序底部输入框被输入法遮住？TaoToken 场景下 cursor-spacing 配置与验证

1. 底部输入框被键盘顶飞，问题到底出在哪

微信小程序里做聊天页、评论页、客服对话页，底部固定一个输入框几乎是标配。但真机一测，很多人会遇到同一个画面：手指点进输入框，键盘“唰”地弹起来，输入框要么被整个盖住，要么只露出半截，用户根本看不到自己正在打什么字。更诡异的是，开发者工具里一切正常，只有真机、只有部分机型、只有某些输入法才会复现。

这个问题的本质，是小程序的键盘弹起行为和页面布局之间的配合没对齐。键盘弹起时，微信客户端会尝试把页面往上顶（adjust-position 默认就是开启的），但“顶多少”这件事，取决于输入框当前的位置、光标位置、以及你给cursor-spacing设的值。如果这几个参数没配好，就会出现顶过头、顶不够、或者干脆不顶的情况。

我先把结论摆出来：底部输入框被遮挡，90% 的情况靠cursor-spacing+adjust-position两个属性就能解决，剩下 10% 需要配合bindfocus事件手动监听键盘高度做兜底。这篇文章就围绕这四个角度——cursor-spacing、adjust-position、focus事件、键盘高度监听——把配置、验证、排障一条龙讲清楚。

适合谁看：正在写小程序聊天/评论/客服页的开发者，尤其是被“开发者工具正常、真机翻车”折磨过的同学。你不需要很深的底层知识，跟着配置片段改一遍，再用真机验证步骤跑一遍，基本就能定位问题。

先明确一个概念，避免后面混淆。cursor-spacing指的是光标和键盘顶部之间的距离，单位是 px。微信的官方说明里有一句很关键的话：取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值，作为光标与键盘的距离。这句话是理解所有遮挡问题的钥匙，后面第 3 节会展开。

而adjust-position是一个布尔值，默认true，表示键盘弹起时是否自动上推页面。很多人一遇到遮挡就把它设成false，结果页面不顶上去了，输入框反而被键盘彻底盖死——这是个典型误区，第 5 节会专门讲。

还有一个容易被忽略的点：输入框是不是position: fixed固定在底部。如果是 fixed 布局，页面整体上推时，fixed 元素的行为和普通文档流元素不一样，这也是遮挡的高发区。所以配置之前，先确认你的输入框是怎么定位的。

2. TaoToken 场景下的前置准备与接入配置

在动手改cursor-spacing之前，先把“模型能力”这一层接好，因为聊天页最终是要把用户输入发给大模型的。这里我用 TaoToken 来做接入层，它提供 OpenAI 兼容的接口，小程序里用wx.request就能直接调，不需要额外 SDK。

先说清楚 TaoToken 是什么、能做什么、适合谁。它是一个大模型 API 聚合服务，对外暴露统一的 OpenAI 兼容接口，你拿到一个 API Key 之后，就能用同一套请求格式调用不同厂商的模型。对于小程序这种不方便引入重型 SDK 的环境来说，这种“一个 Base URL + 一个 Key + 一个 Model ID”的模式非常省事。适合正在做 AI 聊天、AI 客服、AI 评论助手这类小程序的开发者。

接入需要三样东西，我把它叫做“三件套”，缺一不可：

• Base URL：https://taotoken.net/api
• API Key：在控制台创建，形如sk-xxxx
• Model ID：比如gpt-4o-mini、claude-3-5-sonnet这类模型标识

获取 Key 的入口在控制台的 API Keys 页面，创建后记得复制保存，页面刷新后就看不全了。如果你还没决定用哪个模型，可以先去模型对话页面试一下效果，确认响应速度和输出质量符合预期，再回到代码里写死 Model ID。

这里给一个最小可用的请求示例，语言标注为 javascript，放在小程序的utils/request.js里：

// utils/request.js const BASE_URL = 'https://taotoken.net/api'; const API_KEY = 'sk-你的Key'; // 生产环境请放到后端代理，不要硬编码在小程序里 const MODEL_ID = 'gpt-4o-mini'; function chatCompletion(messages) { return new Promise((resolve, reject) => { wx.request({ url: `${BASE_URL}/v1/chat/completions`, method: 'POST', header: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${API_KEY}` }, data: { model: MODEL_ID, messages: messages, stream: false }, success: (res) => { if (res.statusCode === 200) { resolve(res.data.choices[0].message.content); } else { reject(new Error(`HTTP ${res.statusCode}: ${JSON.stringify(res.data)}`)); } }, fail: (err) => reject(err) }); }); } module.exports = { chatCompletion };

注意：小程序正式上线时，API Key 不要直接写在前端代码里，建议走自己的后端做一层转发，前端只调自己的域名。上面这样写只是为了本地联调方便。

如果你更偏向长期做编码类、Agent 类的项目，可以考虑 Coding Plan，它在调用额度和模型选择上更适合持续开发场景。但就本文这个“底部输入框遮挡”的问题来说，接入层只要保证能正常发出请求、拿到回复就够了，重点还是在 UI 配置上。

接入完成后，建议先跑一次最简单的请求，确认三件套没问题，再去调输入框。因为如果接入本身报错，你会在聊天页看到“发送失败”，那时候很难判断到底是键盘遮挡问题还是接口问题。分开验证，排障效率高很多。

3. 可复制的 input 配置片段与参数拆解

这一节是全文的核心，直接给可复制的配置。先看一个聊天页底部输入框的完整 WXML + WXSS + JS 片段，然后逐参数拆解。

WXML 部分：

<!-- pages/chat/chat.wxml --> <view class="chat-container"> <scroll-view class="msg-list" scroll-y scroll-into-view="{{scrollToId}}" style="padding-bottom: {{keyboardHeight}}px;" > <view wx:for="{{messages}}" wx:key="id" id="msg-{{item.id}}" class="msg-item"> {{item.content}} </view> </scroll-view> <view class="input-bar" style="bottom: {{keyboardHeight}}px;"> <input class="chat-input" value="{{inputValue}}" placeholder="说点什么..." confirm-type="send" cursor-spacing="20" adjust-position="{{false}}" bindfocus="onInputFocus" bindblur="onInputBlur" bindconfirm="onSend" bindinput="onInput" /> <button class="send-btn" bindtap="onSend">发送</button> </view> </view>

WXSS 部分：

/* pages/chat/chat.wxss */ .chat-container { position: relative; height: 100vh; display: flex; flex-direction: column; } .msg-list { flex: 1; overflow-y: auto; } .input-bar { position: fixed; left: 0; right: 0; bottom: 0; display: flex; align-items: center; padding: 12rpx 20rpx; background: #fff; border-top: 1rpx solid #eee; transition: bottom 0.2s ease-out; } .chat-input { flex: 1; height: 72rpx; padding: 0 20rpx; background: #f5f5f5; border-radius: 36rpx; font-size: 28rpx; }

JS 部分，重点是键盘高度监听：

// pages/chat/chat.js Page({ data: { messages: [], inputValue: '', keyboardHeight: 0, scrollToId: '' }, onInputFocus(e) { // 记录聚焦时的键盘高度，部分机型 focus 时就能拿到 const height = e.detail.height || 0; this.setData({ keyboardHeight: height }); }, onInputBlur() { this.setData({ keyboardHeight: 0 }); }, onInput(e) { this.setData({ inputValue: e.detail.value }); }, onSend() { const text = this.data.inputValue.trim(); if (!text) return; // 这里调用第 2 节的 chatCompletion this.setData({ inputValue: '' }); } });

现在逐参数拆解，这是理解遮挡问题的关键。

cursor-spacing：光标与键盘的距离，单位 px。官方那句“取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值”怎么理解？假设你的输入框距离屏幕底部 100px，cursor-spacing设成 20，那么微信会取min(100, 20) = 20，也就是让光标距离键盘顶部 20px。如果你设成 200，取min(100, 200) = 100，光标就贴着输入框原来的位置。所以这个值不是越大越好，设太大等于没效果，设太小输入框会紧贴键盘。底部输入框一般设 20 到 40 比较舒服。

adjust-position：默认true，键盘弹起时自动上推页面。注意，它推的是整个页面，不是单独推输入框。如果你的输入框是position: fixed固定在底部，页面整体上推时，fixed 元素的表现会因机型而异，这就是为什么很多人设了adjust-position="true"还是被遮挡。本文的配置里我把它设成false，改用keyboardHeight手动控制bottom，这样行为最可控。

bindfocus：聚焦事件，e.detail.height在部分机型上能直接拿到键盘高度。但注意，不是所有机型在 focus 时都能拿到准确高度，有些机型返回 0，需要配合下面的键盘高度监听兜底。

键盘高度监听：微信提供了wx.onKeyboardHeightChange，这是最可靠的键盘高度来源。把它加到onLoad里：

onLoad() { wx.onKeyboardHeightChange((res) => { this.setData({ keyboardHeight: res.height }); }); }

有了这个监听，输入框的bottom就会跟着键盘高度实时变化，键盘弹起时输入框被顶到键盘上方，键盘收起时回到 0。这套组合拳下来，遮挡问题基本就解决了。

提示：wx.onKeyboardHeightChange在页面onUnload时最好用wx.offKeyboardHeightChange解绑，避免页面销毁后回调还在跑。

4. 真机验证步骤与不同机型对比记录

配置写完，开发者工具里看着没问题，但这不代表真机没问题。下面是我实测下来的一套验证流程，按顺序做，能快速确认修复是否生效。

第一步，用真机预览，不要用模拟器。开发者工具的键盘模拟和真机差异很大，尤其是键盘高度和弹起动画。点击开发者工具的“预览”，用手机扫码打开。

第二步，打开调试模式。在手机小程序右上角菜单里打开“开发调试”，这样能看到console.log输出。在onInputFocus和onKeyboardHeightChange里各加一行日志，打印键盘高度：

wx.onKeyboardHeightChange((res) => { console.log('键盘高度变化:', res.height); this.setData({ keyboardHeight: res.height }); });

第三步，依次测试四种场景：点击输入框弹出键盘、输入文字、点击键盘上的“发送”、点击输入框外部收起键盘。每种场景都观察输入框是否完整可见、光标是否在可视区域内、消息列表是否被正确顶起。

第四步，切换输入法再测一遍。这是最容易被忽略的一步。系统自带输入法、第三方输入法（如搜狗、百度）的键盘高度不一样，有些输入法还有候选词栏，会额外增加高度。我实测下来，同一台手机上，系统输入法和第三方输入法的键盘高度能差 40 到 80px。

下面是我在几台机型上的对比记录，供参考（数值为键盘高度，单位 px）：

从这张表能看出两个规律：一是第三方输入法普遍比系统输入法高，二是cursor-spacing设太大（比如 100）会让输入框被顶得过高，反而不好看。所以底部输入框我推荐 20 到 40，而不是网上很多文章里写的 100。

第五步，测试横屏和分屏（如果你的小程序支持）。横屏时键盘高度和竖屏不同，keyboardHeight监听依然有效，但布局要单独适配。

第六步，回归测试。改完配置后，把聊天页的所有交互再走一遍：发送消息、滚动消息列表、连续快速点击输入框。确认没有出现输入框闪烁、位置跳动、键盘收起后输入框不回位等问题。

我踩过的一个坑是：keyboardHeight变化时给bottom加了 CSS transition，结果在某些安卓机型上动画卡顿，输入框会“飘”一下才到位。后来把 transition 时间从 0.3s 改成 0.2s，并加上ease-out，才顺滑起来。如果你也遇到类似情况，可以调这个值。

5. 本篇常见报错与遮挡排查

这一节把常见的报错和遮挡场景列出来，对照排查。注意，这里的“报错”既有控制台错误，也有“看起来没报错但就是不对”的现象。

现象一：输入框被键盘完全盖住，页面没有任何上推。先检查adjust-position是不是被设成了false，同时keyboardHeight监听没生效。如果你用了本文的手动方案，确认wx.onKeyboardHeightChange有没有注册成功。可以在回调里打日志，如果日志不打印，说明监听没生效，检查是不是写在了onLoad之外。

现象二：控制台报request:fail url not in domain list。这是小程序域名白名单问题，和键盘无关，但接入 TaoToken 时经常遇到。解决方法是去小程序后台的“开发设置 - 服务器域名”里，把https://taotoken.net加到 request 合法域名里。本地调试可以勾选“不校验合法域名”。

现象三：控制台报401 Unauthorized。这是 API Key 问题。检查三件套里的 Key 有没有复制完整、有没有多余空格、有没有过期。TaoToken 的 Key 在控制台 API Keys 页面管理，如果确认 Key 没问题，检查请求头是不是Authorization: Bearer sk-xxx格式，Bearer和 Key 之间有一个空格，别漏了。

现象四：控制台报Cannot read property 'choices' of undefined。这是解析响应时res.data.choices不存在。常见原因是请求失败但走了 success 分支，或者返回结构和你预期的不一样。加一层判断：先看res.statusCode是不是 200，再看res.data.choices存不存在。如果用的是流式返回（stream: true），响应结构完全不同，不能按choices[0].message.content取。

现象五：输入框位置正确，但消息列表被键盘挡住，看不到最新消息。这是scroll-view的高度没跟着键盘调整。本文配置里给scroll-view加了padding-bottom: {{keyboardHeight}}px，确保列表底部留出键盘的空间。如果还是不行，检查scroll-into-view有没有指向最新消息的 id。

现象六：键盘收起后输入框不回位，停在半空。这是keyboardHeight没有归零。wx.onKeyboardHeightChange在键盘收起时会回调height: 0，正常情况下会自动归零。如果没归零，检查是不是在onBlur里手动 setData 覆盖了监听的值，两者冲突了。建议只保留监听，不要在 blur 里再设一次。

现象七：部分安卓机型 focus 时e.detail.height为 0。这是机型差异，不是 bug。所以不要只依赖bindfocus的高度，一定要用wx.onKeyboardHeightChange兜底。本文的方案就是两者结合，focus 时先设一次，监听再实时更新。

现象八：local proxy failed或网络请求超时。这通常是本地网络环境问题，检查手机和电脑是不是同一网络、有没有开代理工具。小程序请求走的是手机网络，和电脑的代理设置无关，如果手机本身网络受限，请求会失败。换个网络环境再试。

排查的核心思路是：先确认是 UI 问题还是接口问题。如果输入框本身位置就不对，那是 UI 配置问题，看现象一、五、六；如果输入框位置对但发不出消息，那是接口问题，看现象二、三、四、八。分开定位，效率高很多。

6. 把配置沉淀成可复用的输入框组件

聊到最后，给一个实用建议：把上面这套配置沉淀成一个独立的输入框组件，而不是每个页面复制一遍。小程序的自定义组件很适合做这件事。

新建一个components/chat-input组件，把input、keyboardHeight监听、cursor-spacing配置都封装进去，对外只暴露value、bindsend两个属性。这样聊天页、评论页、客服页都能复用，改一处全局生效。

组件化的另一个好处是，键盘高度监听的注册和解绑都收在组件内部，不会污染页面逻辑。组件attached时注册wx.onKeyboardHeightChange，detached时解绑，干净利落。

如果你后续要接更多模型能力，比如让输入框支持“@ 某个 AI 角色”、支持语音转文字，组件化之后扩展也方便。接入层继续用 TaoToken 的三件套，UI 层用封装好的输入框组件，两边解耦，维护起来轻松很多。

最后留一个我实测有效的参数组合，直接抄：cursor-spacing="20"、adjust-position="{{false}}"、wx.onKeyboardHeightChange监听键盘高度、输入框bottom绑定keyboardHeight。这套组合在 iPhone 和主流安卓机型上都能让底部输入框完整可见，第三方输入法下也不会被遮挡。你先按这个跑一遍，如果还有机型不生效，再回到第 5 节对照排查。