微信小程序 input 键盘遮挡怎么办？用 cursor-spacing 拉开输入框与键盘的距离

1. 真机聚焦时 input 被软键盘顶飞的典型场景

微信小程序里input组件在开发者工具里看着一切正常，真机一聚焦，软键盘弹起来直接把输入框盖住，用户打字时完全看不到自己输的内容。这个问题在聊天输入框、表单底部字段、弹窗内输入框里出现频率最高，尤其是页面底部固定定位的输入区域。

先说清楚cursor-spacing是什么。它是微信小程序input和textarea组件的一个属性，单位是 px，作用是控制「光标位置与软键盘顶部之间的最小距离」。当输入框聚焦、软键盘弹出时，微信会根据这个值把页面往上推，保证光标和键盘之间留出你指定的空间。默认值是 0，所以不设置的时候，键盘紧贴输入框，视觉上就像被遮挡了。

适合谁看：正在做小程序表单、聊天、评论、地址填写这类需要频繁输入的开发者；已经试过adjust-position但效果不理想的同学；以及被真机与模拟器表现不一致坑过的人。

我试过在一个底部固定输入栏的项目里，模拟器完全没问题，真机 iOS 上键盘一弹，输入框直接消失。后来发现就是没设cursor-spacing，加上cursor-spacing="20"之后立刻正常。这个属性看起来简单，但配合adjust-position、fixed定位、scroll-view使用时有不少细节，下面从配置到真机验证一步步拆开讲。

核心检索词先明确：微信小程序 input 键盘遮挡、cursor-spacing 用法、input 与软键盘距离设置。这三个词基本覆盖了你要解决的问题域。

需要区分两个容易混淆的属性：

很多人以为设了adjust-position="true"就够了，其实它只负责「推不推」，推多少由cursor-spacing决定。两个配合才是完整方案。如果adjust-position设为 false，页面完全不推，cursor-spacing也就没意义了——这点在排查时经常被忽略。

还有一个隐藏坑：当 input 放在position: fixed的容器里，或者放在scroll-view内部时，自动上推的逻辑会受影响。fixed 定位的元素不参与页面滚动，微信的上推机制对它作用有限，这时候往往需要手动监听键盘高度再调整。所以第一步永远是先确认你的 input 处于什么布局环境，再决定用纯属性方案还是属性加手动方案。

2. TaoToken 前置：接入前的账号与 Key 准备

这一节讲的是如果你要把输入内容接到大模型做实时处理（比如输入即联想、输入框内容润色、聊天机器人），需要先准备好调用凭证。纯前端解决键盘遮挡不需要这一步，可以跳到第 3 节。但只要涉及模型调用，Key 和 Base URL 就得先配好。

TaoToken 的接入信息如下，建议直接记下来：

• 官网地址：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 地址：https://taotoken.net/api
• 模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite
• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite
• 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

操作顺序建议这样：先进控制台确认账号状态，再去 API Keys 页面创建一个新 Key，复制后立刻存到安全的地方（页面刷新后不再完整显示）。然后打开接入文档，对照你要用的模型确认 Model ID 的准确写法。Model ID 写错是最常见的 401 之外的第二大报错来源，比如把claude-sonnet-4-5写成claude-sonnet-4.5，请求会直接失败。

如果你用的是 Claude Code 这类命令行工具，还需要配置 Anthropic 兼容的 Base URL，具体参考：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite

这里强调一个原则：Base URL、API Key、Model ID 三件套必须同时正确，缺一不可。很多「连不上」的问题，最后查出来是 Base URL 少写了/api或者多写了斜杠。建议把这三个值写在一个配置文件里统一管理，不要散落在代码各处。

对于小程序场景，Key 绝对不能硬编码在前端代码里，会被反编译拿到。正确做法是小程序请求你自己的后端，后端再带着 Key 去调 TaoToken。前端只负责把输入框内容发给你的服务器。这一点在涉及键盘遮挡的聊天类小程序里尤其重要，因为输入内容往往要实时上送。

3. 可复制配置：WXML 属性与 JSON 片段

这一节给可直接粘贴的代码。先看最基础的 WXML 写法：

<input class="chat-input" type="text" value="{{inputValue}}" cursor-spacing="20" adjust-position="{{true}}" confirm-type="send" bindinput="onInput" bindconfirm="onConfirm" placeholder="说点什么" />

cursor-spacing="20"表示光标与键盘顶部至少留 20px。这个值不是越大越好，太大页面会被推得很高，顶部内容跑出屏幕。一般 10 到 30 之间比较舒服，聊天输入框建议 20，表单底部字段建议 30 到 50。

如果是textarea，写法一样：

<textarea class="comment-box" value="{{comment}}" cursor-spacing="30" adjust-position="{{true}}" maxlength="200" bindinput="onCommentInput" placeholder="写下你的评论" />

注意adjust-position用{{true}}而不是字符串"true"，虽然多数情况字符串也能生效，但布尔属性用数据绑定更规范，避免某些基础库版本解析异常。

接下来是页面配置。如果你的输入框在页面底部，建议给页面加disableScroll或者用scroll-view包裹内容区，避免键盘弹出时整页跳动：

{ "navigationBarTitleText": "聊天", "disableScroll": false, "usingComponents": {} }

disableScroll设为 true 会禁止页面滚动，适合全屏固定布局；设为 false 允许滚动，适合长表单。这个要和你的布局匹配，不能乱设。

如果你的项目用 TypeScript 管理配置，或者需要把模型调用参数也集中管理，可以用一个 TOML 或 JSON 文件存接入信息：

{ "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "modelId": "claude-sonnet-4-5" }, "input": { "cursorSpacing": 20, "adjustPosition": true } }

这个文件放在后端项目里，前端通过接口拿配置，不要直接打包进小程序。

对于用 Cline MCP 或类似工具做开发的场景，配置里同样要写全三件套。以 MCP 配置为例：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的Key", "TAOTOKEN_MODEL_ID": "claude-sonnet-4-5" } } } }

Base URL、Key、Model ID 三个环境变量一个都不能少。少写 Model ID 时，服务端可能用默认模型，但一旦默认模型和你预期不符，返回内容风格会变，排查起来很费时间。

如果你用 Codex 的auth.json，结构类似：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "claude-sonnet-4-5" }

同样三件套齐全。这些配置文件建议加进.gitignore，别把 Key 提交到仓库。

回到键盘遮挡本身，还有一个组合技巧：当 input 在scroll-view里时，给scroll-view加scroll-into-view配合 input 的 id，聚焦时自动滚到可见区域：

<scroll-view scroll-y scroll-into-view="{{intoView}}" style="height: 100vh;"> <view id="inputAnchor"></view> <input id="mainInput" cursor-spacing="20" bindfocus="onFocus" bindblur="onBlur" /> </scroll-view>

Page({ data: { intoView: '' }, onFocus() { this.setData({ intoView: 'inputAnchor' }); }, onBlur() { this.setData({ intoView: '' }); } });

这样聚焦时页面会滚到锚点位置，配合cursor-spacing双保险。实测在长表单里效果比单用属性更稳。

4. 真机验证请求与成功结果

配置写完必须真机验证，模拟器的键盘行为和真机差别很大。验证步骤如下。

第一步，用微信开发者工具的真机调试功能。点击工具栏「真机调试」，用手机扫码，进入调试模式。这一步能拿到真机的键盘高度和页面推挤行为。

第二步，在手机上聚焦输入框，观察三个点：输入框是否可见、光标上方是否留出空间、页面顶部内容是否被推出屏幕。如果输入框可见且光标上方有约 20px 空隙，说明cursor-spacing生效了。

第三步，打开真机调试的控制台，打印键盘高度做对照：

Page({ onFocus(e) { console.log('键盘高度:', e.detail.height); console.log('输入框位置:', e.detail.top); } });

bindfocus的事件对象里有height（键盘高度）和top（输入框距顶部距离）。如果top + 输入框高度 + cursor-spacing > 屏幕高度 - 键盘高度，说明空间不够，需要调大cursor-spacing或者调整布局。

第四步，验证模型调用链路（如果涉及）。在小程序里触发一次输入上送，后端收到后调 TaoToken，返回结果。后端请求示例：

curl -X POST https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-5", "max_tokens": 256, "messages": [{"role": "user", "content": "帮我把这句话润色一下"}] }'

成功返回的 JSON 里会有content数组，第一项的text就是模型输出。如果返回 200 且内容正常，说明 Key、Base URL、Model ID 三件套都对。

第五步，回到键盘遮挡本身，做一次完整交互：聚焦、输入、发送、键盘收起、页面复位。重点看键盘收起后页面有没有正确回弹。有些项目键盘弹起正常，收起后页面卡在半空，这是adjust-position和手动滚动冲突导致的，需要检查有没有在bindblur里重复设置滚动位置。

实测下来，iOS 和 Android 的表现差异主要在键盘高度和动画时长上。iOS 键盘高度约 260 到 300px，Android 因机型而异，有的能到 350px。所以cursor-spacing设一个固定值不一定在所有机型都完美，必要时用bindfocus拿到的height动态计算：

onFocus(e) { const keyboardHeight = e.detail.height; const spacing = keyboardHeight > 300 ? 30 : 20; this.setData({ cursorSpacing: spacing }); }

然后 WXML 里用cursor-spacing="{{cursorSpacing}}"。这样能适配不同机型。

5. 本篇常见报错排查

这一节对照真实报错逐个排查。

报错一：401 Unauthorized。模型调用返回 401，说明 Key 有问题。检查三处：Key 是否复制完整（有没有漏掉前缀）、Key 是否已过期或被删除、请求头字段名是否正确。Anthropic 兼容接口用x-api-key，OpenAI 兼容接口用Authorization: Bearer。用错字段名会直接 401。去 API Keys 页面重新生成一个 Key 再试。

报错二：local proxy failed。这个报错通常出现在命令行工具或 MCP 场景，表示本地代理层没起来或者配置的 Base URL 不通。检查 Base URL 是否写成https://taotoken.net/api，注意结尾不要多加斜杠。再检查网络是否能正常访问该地址。如果是 MCP 配置，确认env里的三个变量都填了。

报错三：reading 'choices' 相关报错。这类报错一般是响应结构和你代码里解析的字段不匹配。OpenAI 兼容接口返回choices数组，Anthropic 兼容接口返回content数组。如果你用 Anthropic 的接口却按choices解析，就会报读取 undefined 的属性。对照接入文档确认接口格式，改解析逻辑。

报错四：OAuth 相关报错。某些工具走 OAuth 流程，如果配置里混用了 API Key 和 OAuth，会报认证方式冲突。确认你用的是 Key 认证还是 OAuth 认证，二选一，不要同时配。用 Key 认证时把 OAuth 相关配置删掉。

报错五：键盘遮挡没解决。如果设了cursor-spacing还是被遮挡，按顺序查：adjust-position是不是被设成了 false；input 是不是在 fixed 容器里（fixed 元素上推机制受限）；是不是在scroll-view里但没配scroll-into-view；cursor-spacing值是不是太小。逐个排除，多数情况是 fixed 布局导致的。

报错六：Model ID 无效。返回模型不存在或无效模型。去接入文档核对 Model ID 的准确拼写，注意大小写和连字符。不同模型的 ID 格式不一样，不能想当然。

排查时建议开真机调试的控制台，把请求参数和响应都打出来。很多问题看一眼原始响应就清楚了，比猜快得多。

6. 长期编码与 Agent 场景的接入建议

如果你不只是解决一次键盘遮挡，而是长期做小程序开发、需要频繁调用模型做代码辅助或 Agent 任务，建议把接入配置标准化。把 Base URL、Key、Model ID 三件套写进项目的环境变量或配置文件，团队共享一份模板，每个人填自己的 Key。

对于需要长期跑编码任务的场景，Coding Plan 更适合：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite

需要验证模型输出效果、快速试不同模型时，用模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite

接入过程中遇到认证或配置问题，先查接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

Key 管理统一在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite

最后回到键盘遮挡这件事，给你一个实用技巧：把cursor-spacing的值做成可配置项，不同页面传不同值。聊天页用 20，表单页用 40，弹窗内输入用 10。这样不用改组件代码，只改传参就行。真机验证时优先测 iOS 和一台 Android 中端机，这两个覆盖了大多数用户的键盘行为差异。配置改完记得清缓存重新编译，有时候旧配置会残留导致你以为没生效。