weapp-cookie

weapp-cookie#

资源概述#

weapp-cookie 是一个小程序 Cookie 兼容库，通过一行代码为小程序原生网络请求添加 Cookie 支持。小程序的 wx.request 接口默认不处理 HTTP Cookie，但许多后端服务依赖 Cookie 维护会话（如 SessionID、CSRF Token）。weapp-cookie 在底层自动代理 wx.request 接口，拦截 Set-Cookie 响应头并存储，在后续请求中自动附加 Cookie，实现与 Web 端一致的会话机制。

支持微信、支付宝、百度、抖音、QQ 小程序，兼容 uni-app / wepy / mpvue 等框架。自 2018 年开源以来持续维护，GitHub 获 849 stars、96 forks，npm 包 weapp-cookie 已发布 33 个版本，是小程序 Cookie 方案的事实标准。

设计规范#

• 无 UI 组件，纯 JS 库
• 零配置使用：在入口文件引入即可自动生效
• 不改变 wx.request 的调用方式，对业务代码透明
• Cookie 存储使用 wx.setStorageSync / getStorageSync 实现
• 支持 domain/path 作用域规则，遵循 RFC 6265 规范

审核规范#

• 库本身不涉及平台审核内容
• 不使用任何敏感 API
• 不影响小程序安全机制，仅在客户端层面管理 Cookie
• 注意：小程序插件环境下 wx.request 不允许被重写，需使用内置别名 wx.requestWithCookie

开发指南#

快速上手#

# 安装
npm install weapp-cookie --save

# 将 npm 包复制到 vendor 文件夹（支持 npm 的环境可跳过）
cp -rf ./node_modules/ ./vendor/

// app.js（小程序入口文件）
// 微信小程序
import './vendor/weapp-cookie/dist/weapp-cookie'

// uni-app / wepy / mpvue（支持 npm 的环境）
import 'weapp-cookie'

App({
  onLaunch() {
    // 引入后 wx.request 已自动支持 Cookie
    // 后续代码无需任何修改
  }
})

// 正常使用 wx.request，Cookie 自动处理
wx.request({
  url: 'https://example.com/login',
  data: { username: 'admin', password: '123456' },
  success(res) {
    // Set-Cookie 已自动存储
    // 后续请求会自动带上 Cookie
  }
})

Cookie API#

import cookies from 'weapp-cookie'

// 获取 cookie
let token = cookies.get('csrf_token', 'example.com')

// 设置 cookie
cookies.set('uid', 100, { domain: 'example.com' })

// 判断是否存在
let has = cookies.has('uid', 'example.com')

// 删除 cookie
cookies.remove('uid', 'example.com')

// 清除所有 cookie
cookies.clearCookies()

// 获取所有 cookie 对象
cookies.dir()

配置别名（插件环境）#

import cookies from 'weapp-cookie'

// 配置自定义请求别名
cookies.config({ requestAlias: 'requestx' })

// 使用别名发起带 Cookie 的请求
wx.requestx({
  url: 'https://example.com/user/current',
  success(res) { console.log(res) }
})

常见陷阱#

1. 插件环境限制：小程序插件内 wx.request 不可重写，必须使用别名模式
2. 引入位置：必须在 app.js 入口最先引入，确保在其他 wx.request 调用前完成代理
3. npm 构建：微信原生小程序需开启「使用 npm 模块」并构建 npm
4. 跨域 Cookie：小程序没有浏览器同源策略限制，Cookie 按 domain 匹配
5. 存储大小：Cookie 存储依赖 wx.setStorageSync，总容量限制 10MB
6. HTTPS 要求：小程序请求必须 HTTPS，Cookie 通过 HTTPS 头传输

从 Web 端迁移#

• 后端无需修改：Cookie 机制完全兼容 Web 端
• 前端：移除手动维护的 token/3rd_session_key 逻辑
• Session 机制：后端 Session 配置不变，weapp-cookie 自动处理 JSESSIONID/SessionID

生态资源#

推荐框架#

• 原生小程序（微信/支付宝/百度/抖音/QQ）
• uni-app：原生兼容
• wepy：原生兼容
• mpvue：原生兼容

相关工具#

• wxrequest：增强版网络请求库
• miniprogram-network：小程序网络层重定义库（NewFuture/miniprogram-network）

社区资源#

• GitHub Issues
• npm 包
• 33 个 npm 版本，持续维护

版本更新#

• v1.4.8（最新）：最新稳定版
• v1.4.x 系列：修复多平台兼容性、Cookie 过期处理
• v1.3.x 系列：新增别名机制（解决插件环境限制）
• v1.2.x 系列：新增 domain/path 作用域支持
• v1.0（2018-03）：初始版本，基础 Cookie 代理
• 项目自 2018 年持续维护，最近更新 2026-07-17