企业官网建设流程全解析

1. 当 AI 编程助手遇上微信小程序：一个真实的需求场景

去年年底我开始重度使用 TRAE 做日常开发，从写 Python 脚本到搭 Node 服务，体验一直不错。但有一个场景始终让我别扭：每次让它帮我改微信小程序的代码，它给出的方案总像是"隔着一层玻璃看东西"——能写逻辑，但对小程序特有的目录结构、app.json配置项、WXML 与 WXSS 的配合方式，经常给出似是而非的建议。最典型的一次，我让它帮我调整一个页面的顶部导航栏高度适配，它直接甩了一段 CSS 的padding-top: 44px，完全没考虑胶囊按钮位置、状态栏高度和wx.getSystemInfoSync()返回的statusBarHeight之间的关系。

这个问题的根源其实不复杂：TRAE 默认的工作上下文里，没有微信小程序的工程结构认知，也没有微信开发者工具的运行反馈。它"看"不到小程序的真实运行状态，只能靠通用前端知识去猜。而微信小程序虽然长得像前端，但它的运行时、渲染层、配置体系跟标准 Web 差别很大——双线程架构、逻辑层与渲染层分离、setData的性能边界、自定义组件的Component构造器、behaviors复用机制，这些都不是通用前端知识能覆盖的。

所以这篇东西想聊的，就是怎么让 TRAE 真正"看"到微信小程序——不是让它瞎猜，而是让它能读到工程结构、能理解配置语义、能拿到运行时的反馈，最终把 AI Coding 的效率真正落到小程序开发上。适合已经在用 TRAE 或类似 AI 编程工具、同时又在做微信小程序的同学参考。如果你还在纠结"AI 到底能不能写小程序"，那这篇可能不太适合你；但如果你已经在用、只是觉得"差一口气"，那接下来的内容应该能帮上忙。

2. 为什么 AI 编程工具默认"看不见"小程序工程

2.1 小程序工程结构的特殊性

先把这个"看不见"说清楚。一个标准的微信小程序工程，目录结构大概是这样：

project/ ├── app.js ├── app.json ├── app.wxss ├── project.config.json ├── sitemap.json ├── pages/ │ ├── index/ │ │ ├── index.js │ │ ├── index.json │ │ ├── index.wxml │ │ └── index.wxss │ └── detail/ │ └── ... ├── components/ │ └── custom-nav/ │ ├── index.js │ ├── index.json │ ├── index.wxml │ └── index.wxss └── utils/

这套结构里，真正让 AI 困惑的不是文件多，而是同名文件承担不同职责、且互相之间存在隐式约定。比如index.json里写"usingComponents": {}是声明自定义组件，写"navigationStyle": "custom"是开启自定义导航栏，写"enablePullDownRefresh": true是开启下拉刷新——这些配置项没有类型提示，AI 只能靠记忆去匹配，一旦记错就会给出错误配置。

再比如 WXML 里的wx:for和wx:key，wx:key的值必须是数组项中某个唯一属性的名字，或者*this。AI 经常写成wx:key="index"，但index并不是数组项的属性，正确写法应该是wx:key="id"或者wx:key="*this"（当数组项是唯一字符串或数字时）。这种细节，通用前端知识里根本没有。

2.2 双线程架构带来的认知断层

微信小程序的运行时是双线程的：逻辑层跑在 JSCore（iOS）或 V8（Android）里，渲染层跑在 WebView 里，两层之间通过setData通信。这意味着：

• 逻辑层拿不到 DOM，document、window这些对象不存在；
• 渲染层不能直接调用wx.开头的 API；
• 所有数据传递都要经过序列化，setData的数据量直接影响性能。

AI 编程工具如果按标准 Web 的思路去写，很容易写出document.getElementById这种在小程序里直接报错的代码。更隐蔽的是性能问题：AI 可能会在一个循环里反复调用setData，或者把整个大对象一次性setData下去，这些在 Web 里可能只是"不够优雅"，在小程序里就是实打实的卡顿。

2.3 开发者工具的运行反馈是缺失的一环

真正让 TRAE "看见"小程序的关键，其实不是让它读更多文档，而是让它能拿到微信开发者工具的运行反馈。开发者工具提供了 CLI 和 HTTP 调用能力，可以触发编译、预览、真机调试，还能读取 console 日志和错误堆栈。如果 AI 能读到这些反馈，它就能形成"改代码 → 编译 → 看报错 → 再改"的闭环，而不是一次性输出一堆可能跑不通的代码。

这也是我后来折腾的重点：不是给 TRAE 喂更多小程序文档，而是给它接上开发者工具这条"眼睛"。

3. 让 TRAE 读懂小程序工程的三层配置

3.1 第一层：工程上下文注入

TRAE 支持通过项目级配置文件来注入上下文。我在项目根目录放了一个.trae/rules.md，内容不是泛泛的"这是一个微信小程序项目"，而是把关键约定写清楚：

# 微信小程序工程约定 ## 目录结构 - pages/ 下每个页面包含 .js/.json/.wxml/.wxss 四个文件 - components/ 下每个组件包含 .js/.json/.wxml/.wxss 四个文件 - 页面和组件的 .json 必须包含 usingComponents 字段（即使为空对象） ## 配置约定 - app.json 的 pages 数组第一项是首页 - 自定义导航栏通过 page.json 的 navigationStyle: "custom" 开启 - 状态栏高度通过 wx.getWindowInfo().statusBarHeight 获取 ## 代码约定 - 禁止使用 document、window、localStorage - 数据更新统一走 this.setData() - 列表渲染必须写 wx:key，值为数组项的唯一属性名 - 网络请求统一封装在 utils/request.js

这份规则文件的作用，是让 TRAE 在生成代码前先"读一遍项目规矩"。实测下来，加了这份文件之后，AI 生成wx:key="index"这种低级错误的概率明显下降。

3.2 第二层：类型定义与 API 提示

微信官方提供了miniprogram-api-typings这个 npm 包，里面包含了所有wx.API 的 TypeScript 类型定义。把它装进项目：

npm install miniprogram-api-typings --save-dev

然后在tsconfig.json或jsconfig.json里引用：

{ "compilerOptions": { "types": ["miniprogram-api-typings"] } }

这一步的意义在于，TRAE 在读取项目时会解析这些类型定义，从而知道wx.getWindowInfo()返回的对象里有哪些字段、wx.request的参数结构是什么。这比让它凭记忆去猜要可靠得多。我对比过，装类型定义之前，AI 写wx.getSystemInfoSync()经常漏掉safeArea字段；装完之后，它会主动用safeArea.top去算安全区域。

3.3 第三层：开发者工具 CLI 打通

这是最关键的一层。微信开发者工具自带 CLI，路径一般在：

• macOS：/Applications/wechatwebdevtools.app/Contents/MacOS/cli
• Windows：C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat

CLI 支持的命令包括：

我在项目里写了一个scripts/dev-tool.sh，封装了常用操作：

#!/bin/bash CLI="/Applications/wechatwebdevtools.app/Contents/MacOS/cli" PROJECT="$(pwd)" case "$1" in open) "$CLI" open --project "$PROJECT" ;; preview) "$CLI" preview --project "$PROJECT" --qr-output "$PROJECT/.preview-qr.png" ;; auto) "$CLI" auto --project "$PROJECT" --auto-port 9420 ;; esac

然后在.trae/rules.md里告诉 TRAE：需要验证代码时，可以调用./scripts/dev-tool.sh preview生成预览，或者用auto模式跑自动化测试。这样 TRAE 就不再是"盲写"，而是有了一个可以触发的验证通道。

4. 用 Cloudbase Skills 补齐服务端能力

4.1 小程序 + 云开发的天然组合

微信小程序和腾讯云开发的结合非常紧密，wx.cloud这套 API 让前端直接调用云函数、云数据库、云存储，省掉了自建后端的麻烦。但 TRAE 默认对云开发的认知比较浅，经常把云函数当成普通 Node 函数来写，忽略了cloud.init()的初始化、event参数的来源、以及云函数返回值的格式要求。

Cloudbase Skills 是腾讯云开发提供的一套能力封装，把常见的云开发操作（数据库增删改查、云函数调用、文件上传）做成了标准化的技能模块。我在项目里引入了这套 Skills 之后，TRAE 生成云函数代码的准确率提升很明显。

4.2 云函数的正确写法

一个典型的云函数长这样：

// cloudfunctions/login/index.js const cloud = require('wx-server-sdk') cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }) exports.main = async (event, context) => { const { OPENID } = cloud.getWXContext() try { const db = cloud.database() const user = await db.collection('users').where({ _openid: OPENID }).get() if (user.data.length === 0) { await db.collection('users').add({ data: { _openid: OPENID, createdAt: db.serverDate(), nickname: '' } }) } return { code: 0, data: { openid: OPENID } } } catch (err) { return { code: -1, message: err.message } } }

这里有几个 AI 容易写错的地方：cloud.DYNAMIC_CURRENT_ENV是动态环境标识，不能写死环境 ID；cloud.getWXContext()拿到的OPENID是微信侧自动注入的，不需要前端传；db.serverDate()是服务端时间，比new Date()更可靠。这些细节，我在.trae/rules.md里都单独列了出来。

4.3 定时任务与自动化

云开发支持定时触发器，配置在云函数目录下的config.json里：

{ "triggers": [ { "name": "dailyTask", "type": "timer", "config": "0 0 8 * * * *" } ] }

这个 cron 表达式是七位的：秒 分 时 日 月 周 年。0 0 8 * * * *表示每天早上 8 点触发。AI 经常按标准五位 cron 来写，结果配置不生效。我在规则文件里专门标注了"云开发定时触发器是七位 cron"，避免它踩这个坑。

5. 实测中踩过的坑与排查链路

5.1 顶部导航栏高度算错导致内容被遮挡

这是我最开始踩的坑。需求是做一个自定义导航栏，内容要正好贴在导航栏下方。我让 TRAE 生成代码，它给的是：

const systemInfo = wx.getSystemInfoSync() const navHeight = systemInfo.statusBarHeight + 44

看起来没问题，但实测在 iPhone 14 Pro 上，内容还是被胶囊按钮挡住了一部分。排查过程是这样的：

第一步，打印wx.getWindowInfo()的完整返回，发现statusBarHeight是 47，safeArea.top是 47，但胶囊按钮的实际位置需要另外算。

第二步，用wx.getMenuButtonBoundingClientRect()拿到胶囊按钮的精确位置：

const menuButton = wx.getMenuButtonBoundingClientRect() // menuButton.top, menuButton.height, menuButton.bottom

第三步，正确的导航栏高度应该是：

const navBarHeight = (menuButton.top - statusBarHeight) * 2 + menuButton.height

这个公式的逻辑是：胶囊按钮上方的间距等于下方的间距，所以导航栏高度 = 状态栏高度 + 胶囊上方间距 + 胶囊高度 + 胶囊下方间距。而胶囊上下间距相等，所以是(menuButton.top - statusBarHeight) * 2 + menuButton.height。

我把这个公式写进了.trae/rules.md，之后 TRAE 再生成导航栏相关代码，就不会再犯这个错了。

5.2 onShareTimeline 写了但分享菜单不出现

这个坑更隐蔽。我在页面里写了onShareTimeline和onShareAppMessage，但在开发者工具里点右上角，只弹出了"分享到朋友"，没有"分享到朋友圈"。排查链路：

第一步，确认onShareTimeline确实写在了 Page 对象里，不是写在 methods 里。

第二步，检查app.json里是否开启了"enableShareTimeline": true。这个配置在基础库 2.11.3 之后才支持，且需要在app.json的window字段下配置。

第三步，确认基础库版本。开发者工具的"详情 → 本地设置 → 调试基础库"要选 2.11.3 以上。

第四步，真机验证。开发者工具的模拟器对朋友圈分享的支持不完整，必须用真机预览才能看到完整效果。

这个排查过程我完整记录了下来，因为 AI 在生成分享相关代码时，经常只写onShareTimeline而忘了app.json的配置，导致"代码写了但功能不生效"。

5.3 setData 性能问题导致的列表卡顿

有一次做一个长列表，TRAE 生成的代码是这样的：

onLoad() { const list = [] for (let i = 0; i < 1000; i++) { list.push({ id: i, name: `item-${i}` }) } this.setData({ list }) }

1000 条数据一次性setData，在开发者工具里还行，真机上直接卡住。排查后发现两个问题：一是数据量太大，二是没有做分页。

优化方案是分页加载 + 局部更新：

onLoad() { this.loadPage(0) } loadPage(page) { const pageSize = 20 const start = page * pageSize const newItems = [] for (let i = start; i < start + pageSize; i++) { newItems.push({ id: i, name: `item-${i}` }) } this.setData({ [`list[${this.data.list.length}]`]: newItems }) }

这里用到了setData的路径更新语法list[index]，只更新新增的部分，而不是整个数组。这个技巧 AI 默认不会用，需要明确告诉它。

6. 把经验固化成可复用的规则

6.1 规则文件的分层组织

折腾了一段时间之后，我把所有踩过的坑和约定整理成了三层规则文件：

• .trae/rules.md：项目级通用约定，包括目录结构、配置规范、代码禁忌；
• .trae/rules-wxml.md：WXML 和 WXSS 的专项规则，包括wx:key写法、样式单位rpx的使用、自定义组件的样式隔离；
• .trae/rules-cloud.md：云开发专项规则，包括云函数写法、数据库操作、定时触发器配置。

分层的好处是，TRAE 在处理不同类型文件时，可以只加载相关的规则，避免上下文过长导致关键信息被稀释。

6.2 规则文件的写法要点

写规则文件有几个心得：

第一，用肯定句，不用否定句。写"列表渲染必须写 wx:key，值为数组项的唯一属性名"，比写"不要用 wx:key='index'"更有效。AI 对肯定指令的遵循度更高。

第二，给具体例子。规则里直接放一段正确代码，比抽象描述管用。比如导航栏高度计算，我直接把公式和注释贴进去。

第三，标注版本依赖。小程序基础库版本更新很快，某些 API 有最低版本要求。在规则里标注"此 API 需要基础库 2.11.3+"，能避免 AI 在低版本项目里用高版本 API。

第四，定期更新。每次踩新坑，就把解决方案补进规则文件。这个文件是活的，不是一次写完就完事。

6.3 验证规则是否生效

规则写完之后，怎么知道 TRAE 真的读了？我的做法是故意在规则里放一条"反常识"的约定，比如"本项目所有日期格式化统一用 utils/format.js 里的 formatDate 函数，不要用第三方库"。然后让 TRAE 写一段日期格式化代码，看它是否引用了utils/format.js。如果引用了，说明规则生效；如果它用了dayjs或moment，说明规则没被读到，需要检查文件路径和格式。

7. 关于 AI Coding 在小程序场景的一些个人体会

用 TRAE 做小程序开发这几个月，最大的感受是：AI 编程工具的价值不在于"替你写代码"，而在于"替你记住那些你记不住的细节"。小程序的 API 有几百个，配置项有几十个，没有人能全部记住。AI 的优势是它见过足够多的代码，能快速给出一个"大概率正确"的方案。但这个"大概率"要变成"确定"，需要你给它足够的上下文和反馈。

我现在的习惯是：让 TRAE 写第一版代码，然后我自己跑一遍，把报错和异常反馈给它，让它改。这个"写 → 跑 → 改"的循环，比一次性让它写完美代码要高效得多。而让这个循环跑起来的前提，就是它能"看见"小程序的运行状态——这就是前面说的开发者工具 CLI 打通的意义。

另外一点体会是，规则文件不要写太长。我一开始把能找到的小程序规范全塞进去，结果 TRAE 反而抓不住重点。后来精简到只保留"我实际踩过坑的"和"项目特有的"两类，效果反而更好。通用的、官方文档里写得很清楚的东西，不用重复。

最后分享一个小技巧：如果你在做一个多端项目（比如同时有微信小程序和支付宝小程序），可以在规则文件里用条件块区分平台差异。TRAE 支持读取这种条件标记，生成代码时会根据当前文件路径判断平台。这个用法我是从 Cloudbase Skills 的文档里学来的，实测在跨端项目里很省事。