企业官网建设流程全解析

简介：这份开源资源是微信小程序「素颜诗」的原始码，面向小程序开发者和诗词内容创作者，也适合想通过真实项目学习开源协作的新手。项目以诗词创作与欣赏为核心场景，完整展示了轻量内容型小程序从配置、页面、样式到逻辑的实现过程。压缩包共30个文件、约105KB，包含7个PNG图片、6个JSON配置、6个JS脚本、5个WXSS样式、4个WXML页面结构、1个Markdown说明及1个JPG预览图，其中JSON负责配置、WXML/WXSS构建界面、JS承载交互逻辑，覆盖了小程序开发的常见模块。目前已有131人学习下载，代码按典型结构组织，包含登录云函数、页面路由、数据绑定等可复用写法，可帮助理解微信开发者工具配置、组件化开发与模块拆分思路，并允许在开源协议下自由学习、修改与二次分发；对于小程序云开发入门者而言，是难得的实操参照。 「素颜诗」（suyan）大概是我做过最"不技术"的一个微信小程序。产品上它只做一件事：让用户用不加修饰的文字记录当下，可以是一句短诗、一条情绪碎语，然后自动排成一张素净的卡片分享出去。名字里的"素颜"说白了就是反滤镜，不搞花哨模板，内容本身就是全部。但真到了写代码的阶段，它又"技术"得不能再技术：登录、发布、信息流、支付、订阅消息、版本更新、分包、隐私合规，一个独立小程序要趟的坑我基本都趟了一遍。这篇文章就把这套小程序原始码从头到尾拆一遍，顺便说说那些官方文档不会写清楚、只有真上线才会撞上的细节。

1. 「素颜诗」的产品逻辑与源码结构：先搞清楚自己拿到的是什么

1.1 从"素颜记录"到"一句话成诗"

产品概念其实不复杂。现在市面上写作类小程序普遍做得太重：多级分类、瀑布流、社交关系链，用户打开以后根本不知道要干什么。素颜诗反着来，发布页就是一张大白纸加一个光标，没有排版工具栏、没有滤镜，你写了什么它就展示什么，最多让你选一个心情标签和当下的天气。上线前我犹豫过很久，怕这种极简风没人用，结果数据告诉我，用户留存最高的恰恰是最"素"的那条路径。

整个产品围绕"素颜"这个视觉概念展开。默认字体是系统字体，卡片背景是近似纸质的暖白，连分享图都用canvas画，不依赖任何图片模板。技术上这也是刻意的选择：图片模板意味着资源包变大、加载变慢，而canvas绘制只需要几十行代码，还能实时改样式。后续如果你想换卡片风格，只需要改canvas绘制函数，不用动页面结构。

1.2 源码目录一目了然：先认清这是原生加云开发

我在项目里没有引入任何第三方框架，目录结构是标准的微信原生小程序加云开发。第一眼拿到这套源码时，建议先看顶层结构：

project.config.json # 项目配置：AppID、编译设置、云开发配置 miniprogram/ app.js # 全局逻辑，启动时调用 login 云函数 app.json # 页面注册、窗口样式、分包配置 app.wxss # 全局样式变量，换皮重点 pages/ index/ # 首页信息流 publish/ # 发布页 detail/ # 诗词详情 profile/ # 我的 components/ poem-card/ # 诗词卡片组件，多个页面复用 nav-bar/ # 自定义导航栏组件 utils/ request.js # 云函数调用封装 cloudfunctions/ login/ # 登录，返回 openid 与自定义登录态 publishPoem/ # 发布，写库 getPoems/ # 信息流分页 pay/ # 微信支付统一下单

这套结构能跑通，核心在于"原生 + 云开发"是一个闭环。页面通过 wx.cloud.callFunction 调用云函数，云函数内部操作云数据库，不需要自建服务器，也不用管域名备案。目录里的 components 不是摆设，poem-card 在首页、详情页、收藏页都会被引用，所以单拆成组件；nav-bar 则是为了配合自定义导航栏，后面的章节我会专门讲。

拿到任何一套小程序源码，第一件事都不是点"编译"跑起来，而是先看 project.config.json 里的 appid，再看每个云函数里 cloud.init 的环境ID。这两个配置不对，你运行起来会收获一堆invalid env和登录失败，这是新手最容易卡住的第一个地方。

2. 技术选型复盘：为什么是原生微信小程序加云开发

2.1 原生开发、uni-app、HBuilderX与AI辅助的取舍

项目刚起步时，我在技术选型上来回摇摆过。身边有人用 HBuilderX 加 uni-app 写跨端应用，也有人用 Codex 之类的AI工具一次性生成整个页面骨架。我后来还是回到原生微信小程序，理由分三点。

一是生态契合度。这个小程序重度依赖微信私有能力：云开发、订阅消息、wx.requestPayment、UpdateManager，这些能力在原生环境里支持最完整、文档最直接。uni-app 虽然用条件编译也能调，但每更新一个基础库版本，都可能出现适配问题，维护成本并不低。二是调试链路。原生小程序的开发者工具对云函数、数据库、Storage 的状态展示非常直观，错误定位快。三是产品边界明确。素颜诗不做App、不做H5，只服务微信用户，没必要为"多端"预先买单。

AI生成代码我也试过，结论是：它适合搭首页静态结构，比如一个带tabBar的三页面框架，五分钟就能给你一个能跑的Demo。但一旦涉及登录态、支付回调、云函数权限这类上下文比较重的逻辑，AI写出来的代码往往似是而非，你不仅要逐行Review，还得自己理解加密和签名的完整流程。省下的时间会以另一种方式还回去。

2.2 整体架构与"原始码"的边界

架构上我坚持用云函数做中间层，而不是让小程序前端直接写云数据库。有人觉得直接在小程序端用 db.collection('poems').add() 更简单，确实快，但业务逻辑全暴露在客户端，权限控制只能靠数据库权限模板，很容易出现"A用户改了B用户的数据"这类事故。素颜诗的所有写入路径都走云函数，云函数内部校验调用者的 openid 与传参是否匹配，再决定放行还是拒绝。

这让我想到一个很重要的认知：所谓"原始码"只是地基，不是成品。很多人以为拿到一套源码，改个logo就能提交审核，现实远没有那么简单。第一，你要把云开发环境、数据集合、隐私协议全部初始化；第二，任何一个依赖外部账号的页面都要重新配置；第三，微信审核看的是"你的产品"而非"你的代码"。源码的价值在于帮你把路走通一遍，而不是替你做完产品决策。

3. 登录、发布与首页信息流：最核心三段链路的代码拆解

3.1 wx.login登录态：一个真实报错引发的排查

这套源码开发到中后期，测试同学真机上报过一个"登录后获取微信用户失败"的错，日志里带了一串类似 wx1cb4398e1413dce7 的标识。这个标识其实是发起登录时的小程序AppID，看到它先别慌，那不是错误码，而是微信在提示"你前端用的AppID和云端环境对不上号"。

排查链路我按这个顺序走：

1. 先看 project.config.json 里的 appid 是不是你自己的小程序AppID；
2. 再到微信公众平台确认云开发环境ID，云函数里 cloud.init 的环境ID是否正确；
3. 检查数据库 users 集合是否存在，某些版本云函数首次部署时不会自动建集合；
4. 最后检查代码里 getUserProfile 是否在用户点击事件后调用——新版基础库已经不允许在 onLoad 里直接读了。

登录云函数的核心代码其实很短：

const cloud = require('wx-server-sdk') cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }) exports.main = async () => { const { OPENID } = cloud.getWXContext() const db = cloud.database() const users = db.collection('users') const res = await users.where({ _openid: OPENID }).get() if (res.data.length === 0) { await users.add({ data: { _openid: OPENID, createdAt: Date.now() } }) } return { openid: OPENID } }

注意 cloud.DYNAMIC_CURRENT_ENV 这个写法，它会自动使用当前云函数所在环境，避免你手动写死环境ID。云开发数据库还会在每条记录上自动注入 _openid 字段，所以很多场景下你都不需要自己维护 session，直接用记录归属判断即可。

3.2 发布与信息流的数据结构

发布页的数据模型一开始特别简单，后来根据使用场景加了一些字段，最终 poems 集合长这样：

首页信息流通过 getPoems 云函数按 createTime 倒序分页返回，一次取10条，同时返回 hasMore 供前端判断。数据量小的时候直接 skip+limit 没问题，等数据量上来，建议改成游标查询：记录上一页最后一条的 createTime，下次查询用where({ createTime: db.command.lt(lastTime) })，性能会稳很多。

我踩过的一个坑是：列表页没有给 createTime 建索引。数据只有几百条时看不出来，到了上千条后排序查询明显变慢，云函数执行时间飙升。去云开发控制台的数据库-索引管理里把 createTime 和 _openid 组合索引建上，问题立刻解决。

3.3 自定义导航栏与用户头像昵称的正确用法

素颜诗的页面顶部没使用系统导航栏，而是在 app.json 对应页面里设置了"navigationStyle": "custom"。原因很直接：系统导航栏样式不可控，胶囊按钮离页面内容太近，和"素颜"的从容感完全不搭。自定义导航栏需要计算高度，核心代码是这样：

const { statusBarHeight } = wx.getWindowInfo() const menu = wx.getMenuButtonBoundingClientRect() this.navBarHeight = (menu.top - statusBarHeight) * 2 + menu.height this.navBarTop = menu.top

为什么这么算？因为胶囊按钮在导航栏里是垂直居中的，用它的 top 减去状态栏高度，就得到导航栏超出状态栏的部分，乘2再加上胶囊自身高度，就是导航栏整体高度。这段代码几乎可以原样复用到任何自定义导航栏的小程序里。

头像昵称这里也踩过坑。早期版本用wx.getUserInfo拿用户头像和昵称，后来微信改了规则，这个方法已经拿不到真实数据。现在标准做法是头像用<button open-type="chooseAvatar">，昵称用<input type="nickname" />。chooseAvatar 返回的是临时文件路径，要先上传到云存储拿到 fileID 再保存；nickname 输入框在微信键盘下会自动弹出用户已有的昵称，省去手动输入的麻烦。改完之后，用户信息页瞬间清爽了很多。

4. 支付、订阅消息、版本更新与分包：从能用到商用的关键配置

4.1 微信支付接入的完整链路与SaaS对接注意点

上线一个月后，我开始考虑"数字诗集"这种轻量付费场景，于是接入了微信支付。整体链路是：用户点购买 → 小程序端调云函数 → 后端调用微信支付统一下单 → 拿到 timeStamp、nonceStr、package、signType、paySign 五个参数 → 小程序端wx.requestPayment拉起支付面板。

云开发环境里可以直接用cloud.cloudPay.unifiedOrder，封装程度很高，个人开发者不用自己维护证书和签名。但如果你是基于源码二次开发，并且已经有自己的Python或PHP后端，完全可以把支付逻辑放在服务端，小程序只负责展示和收尾。关键点在于统一下单的签名流程和回调验签，微信官方文档里有现成模板，别自己发明签名算法，很容易因为参数顺序不对而签名失败。

SaaS 场景下对接微信支付有几个坑。一个商户号可以绑定多个小程序AppID，但需要在公众平台后台做关联配置；回调地址必须能区分订单来源，否则多个小程序共用一个后端时，订单会串；金额单位是分，Java用long，PHP用整数，Python用 int，千万别在浮点数上做计算，否则 0.1 加 0.2 的经典问题会直接呈现在账上。

4.2 订阅消息不是"随便推"：一次推送方案的取舍

最初产品想的是"有人点赞你的诗，就通知你"，真做的时候才发现，微信订阅消息的规则是：用户必须主动点一次授权，你才能给他发一条一次性订阅消息。冷启动直接弹授权基本没人点，因为用户还不知道这个通知有没有价值。

素颜诗最后的方案是：用户发布成功后，弹一个"开启被赞提醒"的授权请求，点击才订阅。产品逻辑上这个时机最自然，因为刚写完内容的用户最在意反馈。代码就几行：

wx.requestSubscribeMessage({ tmplIds: ['模板ID'], success(res) { if (res['模板ID'] === 'accept') { // 记录授权状态，后续有人点赞时调用云函数发送 } } })

模板ID要去公众平台后台的"订阅消息"模块申请，一次请求最多只能传三个模板ID。还要注意，长期订阅消息目前只对特定行业开放，普通开发者的订阅消息基本都是一次性的，千万别用任何号称"绕过授权"的方案，轻则消息发不出去，重则触发风控导致能力被回收。优惠券、活动通知这类模板也是一样的逻辑，先让用户订阅，再在合规范围内触达。

4.3 UpdateManager和subpackages：上线前必做的两件小事

很多维护过线上小程序的人都会遇到一个疑惑："我明明改了代码并发布了，为什么用户手机里还是旧版本？"原因是微信的更新机制存在缓存窗口。解决办法是在启动时注册更新监听：

const updateManager = wx.getUpdateManager() updateManager.onUpdateReady(() => { wx.showModal({ title: '更新提示', content: '新版本已经准备好，是否重启应用？', success(res) { if (res.confirm) updateManager.applyUpdate() } }) }) updateManager.onUpdateFailed(() => { wx.showToast({ title: '新版本下载失败，请稍后重试', icon: 'none' }) })

这段代码要在 onLaunch 里注册，有更新时才会触发提示，不会频繁打扰用户。基础库每次更新都可能改变部分API行为，养成看更新日志的习惯很重要。

另一个上线前必做的是分包。素颜诗首页放在主包，详情页、个人页拆到分包里，主包控制在1MB出头，整体远低于2MB上限。分包配置有几点容易错：分包里的页面路径访问时要带 root 前缀；tabBar 页面不能放进分包；分享链接如果指向分包页面，路径要写全。

5. 上线前后踩坑实录：真机连接、抓包与跳转规则

5.1 真机ERR_CONNECTION_RESET排查链路

真机调试时报net::ERR_CONNECTION_RESET，这个问题在小程序开发里特别典型。第一次遇到时我也一头雾水，开发者工具里一切正常，真机上就是连不上。后来按顺序排查才发现原因：我开着本地调试代理工具干扰了真机流量，关掉之后恢复正常。

这类问题我总结过一条排查顺序，分享给同样被这个报错折磨过的人：

1. 先关闭所有本地代理和抓包工具，很多连接重置的根源是代理干扰；
2. 确认接口域名是HTTPS，并且证书链完整，真机对证书的校验比开发者工具严格；
3. 到公众平台检查 request 合法域名是否配置，开发阶段可以勾选"不校验合法域名"，上线前必须配好；
4. 看云函数日志，确认服务端有没有执行超时或返回异常；
5. 最后才考虑代码层面的问题，比如并发请求过多导致连接池被打满。

遇到网络类报错，最忌讳一上来就改代码。先排除环境问题，再检查配置，最后动代码，能省下大量时间。

5.2 抓包的正确打开方式

开发微信小程序过程中，"抓包"是排查接口问题的常规手段，但很多人用法不对。我自己分两种情况处理。只想看接口参数和返回结果，用开发者工具自带的 Network 面板就够了，能快速看到每个 wx.request 的请求头、响应体和耗时，操作成本为零。需要看得更细，比如定位某个响应字段为什么解析异常，再用桌面抓包工具做HTTPS中间人，需要在电脑上安装根证书，手机连同一局域网并手动配代理，开发工具里勾选"不校验合法域名"。

这里必须强调一句：抓包只应该用来调试你自己开发的小程序和你自己服务的接口。别去抓取第三方小程序的账号、支付和敏感流量，这既是对用户的保护，也是对自己的保护。安全边界不是看技术强弱，而是看用不用在对的地方。

5.3 跳转H5、公众号文章、小程序之间的跳转规则

素颜诗上线后想给用户放一段"产品故事"，就涉及三个跳转场景，踩了一遍坑之后总结如下。

小程序内打开H5用 web-view，但必须在公众平台配置业务域名，域名要求HTTPS、已备案，并且要在域名根目录放一个校验文件。配置完成前，web-view 打开会直接提示"无法打开页面"。打开公众号文章本质上也是用 web-view 打开 mp.weixin.qq.com 的链接，理论上公众号文章本身就允许被 web-view 展示，但需要配合业务域名白名单；实测下来，有些公众号文章会因为对方的隐私设置或插了不允许被嵌入的组件而无法打开，这不是小程序能控制的。

小程序跳小程序用wx.navigateToMiniProgram，直接传目标 AppID 和 path。注意跳转前先检查目标小程序是否允许被跳转，path 写错会在目标小程序里提示页面不存在。A小程序跳B小程序不需要在B后台预注册，但如果两家有业务关联，绑定关联关系后跳转体验会更顺滑。

H5能不能调用微信小程序的经纬度？这是另一个常见问题。在微信内置浏览器里打开H5，可以用微信JS-SDK的 getLocation，前提是公众号后台配置了JS接口安全域名，并由后端完成签名；如果是小程序 web-view 里嵌的H5，可以在H5里通过wx.miniProgram.postMessage向小程序传消息，再由小程序端调用wx.getLocation获得坐标。

5.4 要不要压测：小体量产品的测试边界

热词里有人问"小程序上线前要做压力测试吗"。我的答案是：先判断产品体量，再决定测试深度。素颜诗这类内容型小程序，我上线前用并发脚本对 getPoems 云函数做了1000次调用，重点看失败率和P95耗时，没有做更复杂的全链路压测。原因很简单，云开发会自动扩容，小体量产品最需要关注的不是极限QPS，而是数据库索引、慢查询、云函数超时设置这些实际影响用户体验的细节。

如果你的产品是商城类，那安全性和一致性优先级更高：支付回调要幂等、库存扣减不能超卖、优惠券要防并发刷。这类场景才值得投入更多精力做多接口串联压测和异常恢复测试。判断标准是：预计峰值并发不超过100，优先做功能和真机兼容回归；如果涉及交易和现金，多严谨都不为过。

6. 基于「素颜诗」原始码的二次开发：换皮、合规与个人体会

6.1 换皮三步走：AppID、环境ID、数据库

这套源码拿去改造成自己的小程序，核心路径非常清晰，我把步骤拆成三步。

第一，替换身份。注册自己的小程序，拿到AppID后，替换 project.config.json 里的 appid，同时确认每个云函数都用cloud.DYNAMIC_CURRENT_ENV而不是写死的环境ID。第二，初始化云资源。在云开发控制台创建 users 和 poems 集合，把 cloudfunctions 目录逐个右键"上传并部署：云端安装依赖"，这一步不能省。第三，改品牌。全局样式集中在 app.wxss 里的设计变量，改主色调只需要动几行；tabBar 文案和图标在 app.json 里维护，首页卡片样式在 poem-card 组件里改。

换皮最容易忽略的是隐私协议。微信从2023年起对隐私接口的管控越来越严，调用 chooseAvatar、getLocation 这类接口前，必须在公众平台后台配置"用户隐私保护指引"，并在小程序里处理隐私授权回调。很多人提审被拒，十有八九是这里没配置。小程序类目选择也要慎重，素颜诗这种内容记录类，选"工具-笔记"和"社交-笔记"的资质要求不一样，后者审核更严，按你的实际业务边界选，别为了流量乱选类目。

6.2 把源码变成自己的产品：最后一点个人体会

源码只是一个起点。我在给这套代码做二次开发时最深的体会是：代码能不能跑只是底线，产品上的判断才真正决定这个小程序能不能留下来。素颜诗走到今天，靠的不是某个复杂的交互，而是"素颜"这个概念在每一个页面细节里的坚持——没有花哨动画、没有诱导分享、没有打扰式的推送。

如果你准备拿这套源码做点什么，我建议先想清楚你的"素颜"是什么。是极简记录、是某种小众内容、还是某个垂直人群的情绪出口？确定之后，代码方向自然会清晰。后续还可以扩的方向很多：云函数定时任务做每日精选、接一个大模型API把用户碎碎念改写成古诗、加收藏夹和标签体系，这些在现有源码结构上都不是伤筋动骨的改动。把基础链路吃透，剩下的就是你的想象力了。

本文还有配套的精品资源，点击获取