> 本文整理自平台文档 docs/wujies/5.x/frontends/pc/open-api.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-9ae47c64982b-cover.svg)
这是接入 PC 用户端(以及 H5 / App)时最容易踩的坑,值得单独一页。
一句话
业务性的 C 端控制器都在应用(插件)里。 /open/mall/、/portal/member/、/site/shop 这些路径由对应应用提供;应用没安装,接口就是 404。宿主只留平台能力:/auth/、/system/、/app/**,以及少数几个跨应用接口(/portal/user 个人资料、/open/system/message 消息、/open/{code}/config 站点配置)。
为什么要这样设计
如果 C 端接口写在宿主里,那么每加一个 C 端业务(商城、会员、考试……)都要改宿主、重新编译、重新发版。把 C 端能力随应用走之后:
- 加一个业务 = 装一个应用;
- 应用可以独立升级,不需要重启宿主;
- 用户端只依赖「接口契约」,不依赖「平台版本」。
代价是:接口是否存在,取决于运行期装了哪些应用。 这正是排查时最容易忽略的变量。
排查顺序
接口 404
├─ ① 对应应用装了吗?启用了吗? → 我的应用 / 应用市场
├─ ② 应用版本包含这个接口吗? → 应用详情里的版本与更新日志
└─ ③ 最后才查路径拼写 / 代理配置
不要一上来就查 Nginx 和前端代码。先确认应用装没装,能省掉大部分时间。
在后台「我的应用」里看应用状态;或直接请求后端 GET /app/runtime/enabled-apps,它只要求登录、不校验权限,返回本租户已启用的 appCode 列表(如 ["member","mall"]),前端就靠它决定要不要发这个请求。 后台侧另有 GET /app/install/mine(信息更全,但要 app:install:list 权限,C 端 token 拿到的是 403,不是没装)。
常见接口前缀
| 前缀 | 典型用途 | 提供方 |
|---|---|---|
/open/** | 无需登录的开放数据(商品、内容、配置) | 业务应用;/open/system/message、/open/{code}/config 是宿主 |
/portal/** | 登录用户的门户数据(订单、会员、关注、评论) | 业务应用;/portal/user 是宿主 |
/site/** | 面向匿名访客与搜索引擎的整页 HTML(首页、商品、店铺、图床、企业、考试、询价…),主题资源走 /site/themes、/site/apps/** | 业务应用直接渲染,不是给 SPA 用的 JSON 接口 |
/auth/** | 登录、注册、验证码、刷新 token | 平台宿主 |
/system/** | 字典、地区、用户信息、菜单等基础能力 | 平台宿主 |
/app/** | 应用安装与运行期清单 | 平台宿主(应用市场模块) |
具体路径以各应用的接口清单为准,见 [HTTP 接口索引](/docs/wujies/5.x/platform/reference/api) 与 [开放接口清单](/docs/wujies/5.x/platform/open-api/endpoints)。
登录与 token
- 两端是同一套登录体系:都 POST
/auth/login,都带VITE_APP_CLIENT_ID(同一份配置,对应sys_client里的pc那行)与clientid请求头,Authorization: Bearer <token>; - token 键名也相同(
Admin-Token),所以同域生产部署时后台与用户端共用一次登录;开发态端口不同(后台80、用户端4230、后端8086),origin 不同,localStorage 互相看不见; - 后端直出的
/site/页面不读 localStorage(按 origin 隔离),它看的是后台登录时写的wujies-site-state标记 cookie——只表示"这台浏览器登录过",不含任何凭据**,平台关掉了 cookie 鉴权(is-read-cookie: false)以免开 CSRF 的口子; - 401 时跳登录页;403 是权限不足,不要当成未登录处理。
跨域
开发环境走 Vite 代理,不存在跨域;生产环境两种做法:
1. 同域反代(推荐):VITE_APP_BASE_API=/prod-api,Nginx 转发到后端,顺带让 /site/ 与 SPA 同源; 2. 跨域直连**:VITE_APP_BASE_API 填后端公网地址(当前仓库里是 https://api.wujies.cn/),后端必须允许对应 Origin、Credentials 与自定义头(clientid)。
改了 .env.production 要重新构建,环境变量是构建期注入的。
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-9ae47c64982b-guide.svg)


评论区需要浏览器启用 JavaScript 才能加载。