常见问题

温馨提示

以下常见问题仍无法解决你的疑惑，可尝试进群与群内各位大佬交流沟通。

提问的智慧 🔥🔥🔥

温馨提示

如果您之前在技术类交流群提问时经常没有得到有效反馈，建议先百度搜索或链接直达阅读《提问的智慧》（如果你做惯了“甲方领导”，请必读！）

维护团队成员都是在各自 业余时间 维护（fā diàn）开源项目，有单独全职工作，也有各自生活节奏，所以我们提前告知您：

如果您遇到问题，请先按照 Issue 模板依次排查确认
欢迎您在 Issue 中复现存在的问题，Issue 我们必然响应，并且我们非常欢迎您提个 PR 来修复它
如果您加入了交流群，可以考虑在交流群内与其他用户大佬交流。维护团队成员视个人意愿及空闲时间解答 框架基础使用问题，谢绝技术问题，谢绝微信私信提问
项目在持续迭代中，此刻调研的您如果觉得它无法满足自身需求，也没有什么亮点，那只说明项目与您的需求不太契合，且仍需要迭代，请口下留情转身调研其他同类框架
请勿把维护团队当 “许愿池的王八”，如果你的需求场景仅仅是你的业务，请免开尊口
不接受频繁 “催更”，需求墙里列的后续计划 90% 可能性会做，无非时间精力影响，计划会靠前或靠后，间歇性灵感+爆更，间歇性不想写任何代码，赞助和 star 会强制更新状态

常见差评回复 🔥🔥🔥

“不是所有的鱼生活在同一片海里”
“道不同，不相为谋”

烂大街了，这类项目这么多，老是开发有什么用？看起来也没什么亮点啊。
为什么要用你这个，还要增加学习成本？为什么不直接用 Xxx？
本项目简介中的项目来源有做详细说明，正式立项于作者当时工作需要，工作自用为主，开源的核心目的是共建和持续完善，无心推广和参与竞争，如果恰好能帮到更多人，帮助其梳理一个基础规范模板（“人人都有一套脚手架”），也能满足作者成就感。
作者热衷细节重构，有代码洁癖，所以项目重点始终在于代码质量（主要后端、次要前端）和解决方案细节完成度，欢迎更多 “代码洁癖”、“志同道合者” 多多 “批判”。
为了降低项目上手难度和后期学习成本，在迭代过程中，我们也做了大量的删减和重构，ContiNew Starter 的产生缘由之一也是为了降低学习成本，这是个持续的优化过程，也需要更多志同道合的社区伙伴给出意见和建议。
自己写一个也很快，简单的很，看别人代码头晕
对于认为自己写一个也很快且简单的很，本人不予置评。
但自己写一个，确实是挺好的，如果你有高频的需求，自己封装是个好的选择，这就是本项目来源中提到的沉淀。如果你写不出来，要参考一下，上一个回答里也提到了，如果恰好能帮到更多人，帮助其梳理一个基础规范模板，那也是一件好事。
本项目持续优化代码规范和逻辑细节，如果能改善更多开发者的基础素养，这无疑是好事。
当然了，吃了饭砸锅的事，也不少见，但它们是少数。
初级程序员都爱写后台管理框架，因为简单，收获一些 star，到时候可以在简历里吹嘘。
也许你真的是个大牛天天研究算法不下“基层”无此需求，也许是你的标准太低认定写一个中后台管理框架简单。
作者在公司里也从没透露过所用的 ContiNew 框架是自己主导编写的，更遑论简历中。让领导和同事更多关注到自己，把自己“捧杀”？也许有人真有面试需要，但如果是人家用心开发的，为什么不能写在简历中？

其他

🔥项目有 Java8 版本吗？

有，1.x 版本就是基于 Spring Boot 2.7.x & Java 8 开发的，但早已经停止维护和支持。

分支	仓库地址
1.3.x	Gitee：https://gitee.com/continew/continew-admin/tree/1.3.x/ GitHub：https://github.com/continew-org/continew-admin/tree/1.3.x/

友情提示

ContiNew Admin 1.x 版本，前后端项目均在一个仓库，且没有抽取 ContiNew Starter 组件，前端页面也不是当前演示系统最新效果，风格差异较大，请谨慎选择。
1.x 版本系统效果图可点击前往回顾一个界面现代美观，色彩年轻化的Vue3+SpringBoot3前后端分离中后台管理脚手架。
Spring Boot 3.0 于 2022年11月24日发布，要求从 3.0 开始使用 Java 17 作为最低版本。详情请点击查看 Spring Boot 3.0 发行说明。
Spring Boot 已于 2023年11月24日结束了 2.7.x 及 3.0.x 版本的社区支持。详情请点击查看最新支持情况。
Java 8 于 2014年3月18日发布，这个版本是自 Java 5（发布于2004年）之后的一个重量级版本，也是 Java 发展史上的一个里程碑式的版本，它带来了诸多改进，包括 Lambda 表达式、Streams、日期时间 API 等等。
Java 17 于 2021年9月14日发布，它是一个长期支持版本（Long-Term-Support - LTS）。从 Java 8 过渡到 Java 17 将带来许多新特性和安全、性能方面的改进。详情请点击查看 Oracle JDK 17 文档。
根据 JetBrains 2023 开发者生态系统现状调查报告，经常使用的 Java 版本：Java 8（50%）、Java 17（45%）、Java 11（38%）。详情请点击查看 2023 开发者生态系统现状调查报告。

【您访问本文档的时间：2025/8/18 10:20:51】

项目能开发 Vue2、JS、MyBatis Flex 等等版本吗？

我们欢迎有意愿的大佬扩展 ContiNew 生态并投稿，给更多人群更多选择。

Vue2 本项目开始时已经在逐渐被淘汰，所以从未考虑也无计划开发 Vue2 版本。
JS 版本我们精力有限，无法维护多个版本。
MyBatis Flex，我们有进行调研，如果行业市场普遍采用，我们也会跟进调整技术栈。
...

历史的车轮滚滚向前，ContiNew 项目名称已经体现了（ContiNew，Continue New），我们会持续更新重构，技术栈也将持续跟随行业市场。

项目什么时候上 Cloud？

除技术栈升级考量外，也考虑到为了 cloud 而 cloud 的市场，我们目前在需求计划中已经列了 continew-cloud 计划，但此需求计划优先级很低，提升优先级的可能性就是近期我所在单位会涉及此类项目开发。如你急需 cloud 版本，请调研其他成熟框架。

我们更关注代码质量和解决方案的细节设计闭环，且业余开源精力有限不急于多线拓展，也无心进行项目推广和竞争。

项目有商业版吗？

暂无计划。为爱发电，支持赞助。

多次更换 UI 框架及模板说明

Creator 与 Arco Design 结缘于个人博客项目，认可该 UI 框架的配色方案（好看），同时也认为该 UI 框架的大多数组件足够细腻（好用）。

于是，在 ContiNew Admin 项目初始开发时，确定了 Arco Design Vue 作为 UI 框架，并且选择了官方提供的前端模板（Arco Design Pro）进行扩展开发。直到现在，本人依然认为 Arco Design 这款 UI 框架足够好看好用，甚至它官方推出的前端模板在页面设计上也足够简约大气。

但是，进入实际开发后，本人深刻意识到自己是一位后端开发者，对于前端确实有心无力。尝试封装了一些前端组件，但无论从代码洁癖的角度还是从实用性角度，都不太能达到本人预期。此时也发现 Arco Design Vue 官方推出的 Arco Design Pro 模板更新频率愈来愈低。于是，在经历长时间思量和调研后，（ContiNew Admin >= v3.x ）我们更换前端模板为 林大 开源的（Gi Demo，也称作 Gi Admin Pro ）前端模板。

v3.x 这次更换前端模板的原因，大致如下：

起因：

Arco Design Pro 模板更新频率愈来愈低，很多 Bug 无人修复，依赖也无人升级。（后来已经完全停更，据各方消息，该模板已达到它的使命，所以停止更新）
Arco Design Pro 模板内部组件不成熟（无论是布局还是一些通用工具组件，实际开发发现缺失较多），对于一个专业前端可能还能在其基础上继续增加完善，但对于一个后端开发者，稍显困难，开发体验差。

结论：

Gi Demo 模板基于 Arco Design UI 框架开发，更换前端模板时，3.x 之前的大部分页面代码迁移较为容易。
Gi Demo 模板对于 Arco Design Vue 组件进行了较为丰富的封装，例如：GiForm、GiTable，封装优雅，没有过度封装，实际使用体验佳。
Gi Demo 模板整体样式设计好看。

好好好，那为什么 5.x 还要更换前端模板？

且容喝口水后细说，自 v3.x 版本开发以来，有了 Gi Demo 前端模板基础组件的加持，前端页面开发表格、表单变得更加容易，开发体验上了一个台阶。然而，好事多磨，Arco Design Vue UI 框架的更新频率开始下降，甚至出现过长达数周的停更情况。

v5.x 这次更换前端模板的原因，大致如下：

起因：

Arco Design Vue UI 框架的更新频率降低，目前主要由尚不完善的社区进行维护。
从 ContiNew Admin 项目立项之初，Arco Design UI 框架就属小众之选。多年开发后，它依然小众。企业项目选型时，选择它的也依然属于小众群体。
随着模板开发的深入，也愈发认可一种可持续性较强的前端模板方案，即布局组件自行封装，与 UI 框架解耦（可持续迭代，更灵活，不依赖 UI 框架特性），业务开发则依赖具体 UI 框架，更快捷方便。

暂定结论：

针对 5.x 更换前端模板这一计划，UI 目前暂定为 Element Plus：

[优化] Element Plus 由于问世较早，其默认主题配色已出现审美疲劳，且部分组件细节样式不够细腻。
- 我们也知道目前 ContiNew Admin 项目受众有一部分是 Arco Design 和 Gi Demo 模板圈子的用户，这些用户和我们一样有更高的审美和开发要求，但我们可以确定即使我们更换了 UI 框架，配色方案依然会向 Arco Design 看齐
- 计划结合 art-design-pro 的部分页面设计（例如：仪表盘）

前端模板目前暂定有两个方案：

定制化 Vben Admin5 前端模板
- Vben Admin 前端模板已迭代至5.x版本，整体风格焕然一新，基础框架与布局也更为成熟且丰富；
- [优化] Vben Admin 在行业内以入门困难，项目更适合大型项目而知名，所以我们计划对其进行改造；
  - 计划将 vben 拆成非嵌套项目（简单易上手），并且该模板项目独立持续维护（目前由维护成员番茄大佬抽空实现）
  - 计划将 vben 内过度使用组件的页面调整为代码模式（例如：登录页面）
  - 计划为表格、表单封装一套 GiTable、GiForm 这类的基础组件（搭配 hook），封装程度不深且易用修改
Art Design Pro 前端模板

后端

🔥找不到某个 Bean 或访问接口提示 No endpoint

A：毫不夸张，这是像 NPE、404 一样大多数时候都很容易解决的问题。

场景一： 项目启动报错，提示找不到某个 Bean。

Consider defining a bean of type 'xx.xx.xx.Xxx' in your configuration.

场景二： 项目正常启动，访问接口提示 No endpoint XX。

org.springframework.web.servlet.NoHandlerFoundException: No endpoint XXX /xxx/xx.

它们属于一类问题，都是对应的 Bean（包含 Controller）没有被 Spring 扫描到引起的，你要确认的就是当前你的扫描包配置能不能扫描到对应 Bean/对应 Bean 的实现类/对应 Bean 的配置类等。

要解决这个问题，首先我们需要有几个共识。

Spring Boot Bean 扫描机制
1. Spring Boot 默认扫描启动类（标注了 @SpringApplication 的类）所在的包及其子包
2. 通过 @ComponentScan(basePackages = {"xxx", "xxx"}) 可以配置指定一个或多个不同的扫描包
ContiNew Admin 的包扫描配置
1. 启动类，位于 continew-webapi 模块的 top.continew.admin 包下
2. 没有单独配置 @ComponentScan，采用的是 Spring Boot 默认的包扫描规则，即默认扫描 top.continew.admin 包及其子包下的 Bean
3. 在 application.yml 中有一个 project.base-package 配置，当前仅支持单包，是用于本项目内全局枚举字典扫描等场景的

在有了上述共识之后，请你做如下分析排查（if-else-if-else）：

原版项目（clone 后一个标点符号都没有改动过）是否正常，如原版项目就存在此问题，提个 issue 到开源平台
是否有改动包结构，如果更改包结构，请把 top.continew.admin 包全部更改完整（如果有涉及模块名更改，请注意不要更改 continew-starter 模块名，它是 Maven 外部依赖，非 Admin 内部模块）
启动类所在的包能否扫描到报错的 Bean，例如：启动类在 com.example.admin 包下，报错的 Bean 在 com.example.test 包下，这种是无法扫描到的，除非你单独指定了 @ComponentScan(basePackages = {"com.example"}) 或 @ComponentScan(basePackages = {"com.example.admin", "com.example.test"})`
模块是否有被正确引入或传递引入到 continew-webapi 模块依赖中
通过 @Bean 注解配置的，请排查对应配置类是否有添加 @Configuration 注解
...（自行百度/GPT：Spring 扫描不到 xxx）

无关提醒

IntelliJ IDEA 中某些依赖注入下有红线，如果项目能正常启动请忽略，类似问题想解决可以自行百度。

项目启动后，控制台报 machineId can't be greater than maxMachine[xx] or less than 0.

Q：项目启动后，控制台报错包含下方错误信息：

machineId can't be greater than maxMachine[xx] or less than 0.

A：这是 CosId 的报错，解决方法参见 CosId Issue machineId can't be greater than maxMachine[7] or less than，或者将 CosId 的 machine-bit 位数参数调大一些。

🔥代码生成的功能菜单 SQL 执行插入后，页面还是没有菜单，超管角色功能权限也没有该菜单权限还不能勾选 v3.4.0+

Q：通过代码生成功能，生成了代码及相关功能菜单 SQL，把菜单数据插入后，刷新页面还是没有菜单数据。而且，超管角色功能权限也没有对应权限，还不能勾选。

A：在 ContiNew Admin 3.4.0 的代码生成器中增加了自动生成菜单 SQL 功能，所以很多人添加菜单就是从数据库中直接插入了，导致对应菜单缓存没有更新，只需要从 Redis 中把 MENU 相关缓存健全部删除即可。

v3.6.0 版本，在菜单管理中增加了缓存清理功能，所以你也可以直接在页面操作一下。

超管角色不允许更改功能权限和数据权限，所以页面上不能勾选。
各个角色的菜单权限有缓存，如果是在页面上操作菜单，缓存能及时清理，如果是在数据库中操作，你懂的。

🔥更新了数据库脚本后，启动项目报错

Q：跟进了最新的数据库脚本代码（continew-webapi/.../resources/db/changelog下的脚本文件）后，启动项目报错。

A：请阅读《Liquibase（数据库版本控制工具）》。

使用 SSE 流式传输中断 <v3.7.0

Q：使用 SSE 流式传输中断。

A：原因在于项目引入的 API 请求/响应日志组件 continew-starter-log-interceptor 中定义了一个 LogFilter，目前的解决方法是在配置文件中放行相关 URL。

yaml

--- ### 日志配置
## API 请求/响应日志配置
continew-starter.log:
  # 放行路由
  exclude-patterns: 
    - /xxx

CrudController 添加了 @SaIgnore 注解不起作用 <v3.7.0

Q： CrudController 添加了 @SaIgnore 注解后，依然会被拦截。

A：此问题已经由来已久：https://gitee.com/dromara/sa-token/issues/I8RIBL。

目前的解决方法是：

重写对应需要放行的接口方法，然后增加 @SaIgnore 注解
重写 preHandle 方法，以实现放行鉴权（因为 continew-common/BaseController 里是手动鉴权，所以 @SaIgnore 识别不到）

Q：打开了在线接口文档，想进行接口调试，发现登录接口没有参数。

A：下方是登录接口请求参数实体，我们使用了 @JsonTypeInfo + @JsonSubTypes 来根据 authType 字段自动封装不同登录请求参数实体。而这种风格，Knife4j 这种动态接口文档没有适配显示，不过你倒是可以直接访问 /swagger-ui 查看原生 Swagger UI 页面，这里面能看到请求参数结构。

个人建议： 如果你要直接调试接口，可以在演示环境或你本地环境通过前端实际登录一次，从请求体内复制完整的请求参数再来调用登录接口获取 token 测试，毕竟密码我们是加密传输的，你自己去构建也麻烦。

java

@Data
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "authType", visible = true)
@JsonSubTypes({@JsonSubTypes.Type(value = AccountLoginReq.class, name = "ACCOUNT"),
    @JsonSubTypes.Type(value = EmailLoginReq.class, name = "EMAIL"),
    @JsonSubTypes.Type(value = PhoneLoginReq.class, name = "PHONE"),
    @JsonSubTypes.Type(value = SocialLoginReq.class, name = "SOCIAL")})
@Schema(description = "登录请求参数基类")
public class LoginReq implements Serializable {

    @Serial
    private static final long serialVersionUID = 1L;

    /**
     * 客户端 ID
     */
    @Schema(description = "客户端 ID", example = "ef51c9a3e9046c4f2ea45142c8a8344a")
    @NotBlank(message = "客户端ID不能为空")
    private String clientId;

    /**
     * 认证类型
     */
    @Schema(description = "认证类型", example = "ACCOUNT")
    @NotNull(message = "认证类型无效")
    private AuthTypeEnum authType;
}

🔥我需要加一套对C端用户的接口，接口的鉴权如何处理？

Q：我需要加一套对C端用户的接口，接口的鉴权如何处理？有没有文档参考的？

A： admin 项目在立项之初是为了中后台系统设计的解决方案，目前没有设计多端账号体系。后续我们有计划增加小程序用户端，届时将提供相关设计。

目前你可以参考现有后端用户体系进行补充设计，可参考 SaToken 多账号认证文档进行调整。

涉及的核心类如下，可自行查阅：

top.continew.admin.common.context.UserContext
top.continew.admin.common.context.UserContextHolder
top.continew.admin.auth.AbstractLoginHandler
...

启动项目报错，转换 SaToken 类失败 v3.6.0+

Q：启动项目报错，转换 SaToken 类失败，错误类似如下：

java.lang.ClassCastException: class cn.dev33.satoken.session.SaSession cannot be cast to class java.lang.String (cn.dev33.satoken.session.SaSession is in unnamed module of loader 'app'; java.lang.String is in module java.base of loader 'bootstrap')

A： SaToken 升级到 1.41.0 时，它的部分类做了不兼容升级改动，清空 Redis 里 SaToken 相关 key 再启动即可。

前端

点击导出按钮报错 v2.5.0

Q：点击导出按钮，报错提示如下：

Notification

由于部分模拟数据需要，前端默认启用了 Mock.js，而 Mock.js 会将 responseType 设置为 ''，这不仅会导致关键判断出错，也会导致导出的文件无法打开，实际开发时自行关闭 Mock 即可。

A：如报错提示所述，实际开发时，打开 continew-admin-ui/src/utils/setup-mock.ts，关闭 Mock 即可。

export default ({ mock, setup }: { mock?: boolean; setup: () => void }) => {
  // 在生产环境也启用 mock
  if (mock !== false) setup(); 
  // if (mock !== false) setup();
};

如有需要，实际开发时，除关闭 Mock 外，同时修改 continew-admin-ui/src/components/crud/index.ts 中的导出错误提示。

添加完菜单后路由不可用 v2.5.0

Q：添加完菜单后，点击菜单没有反应，打开控制台后有路由报错。

A：目前前端项目的动态路由，是采用的基础脚手架 Arco Design Pro Vue 的设计方案 #147，作者称之为半动态路由，所以添加完菜单后，还需要在前端 router 下配置一个对应的静态路由（主要是为了指定其组件地址）。

补充问题

2024/2/22：群友 Joshua 使用时发现如果路由配置到 views/basic 目录，即以 /basic 为路由前缀，会出现配置失效的问题，初步怀疑是由关键词污染导致。

配置好后端接口地址，接口 404

Q：下载的 2.5.x 版本前端，配置好后端接口地址后，访问页面报接口 404。

A：前后端版本一定要一一对应，2.5.x 前端只支持后端 2.5.x 版本，友情建议前后端都升级到最新版本。

网络控制台里请求的不是后端，是前端地址

Q：启动后，在浏览器的网络控制台里，请求的 URL 是前端的，而不是后端的。

A：前端基础知识，请先了解下前端的请求过程，前端请求接口后会代理转发到后端的。详情请点击了解。

🔥使用 pnpm 10.x，启动后报错 The package may have incorrect... <v3.6.0

Q：使用 pnpm 10.x，启动后报如下错误，提示。

Failed to resolve entry for package "@vue-office/docx". The package may have incorrect main/module/exports specified in its package.json.

还会有如下警告：

Ignored build scripts: @vue-office/docx, @vue-office/excel, @vue-office/pdf, core-js, es5-ext, esbuild, vue-demi, vue-echarts.
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

A：在 pnpm 10.x 中，有一个重大变化（官方称Major Changes）是：

原文：Lifecycle scripts of dependencies are not executed during installation by default!
译文：默认情况下，安装过程中不会执行依赖项的生命周期脚本！

所以使用 pnpm 10.x 安装依赖时，不会默认执行 vue-office 等依赖的 postinstall 脚本。

解决方法有两个：

降级 pnpm 版本到 9.x
仍然使用 pnpm 10.x，但需要执行 pnpm approve-builds 命令（指定哪些包允许执行 postinstall 命令）

=>参考回答

常见问题 ​

提问的智慧 🔥🔥🔥 ​

常见差评回复 🔥🔥🔥 ​

其他 ​

🔥项目有 Java8 版本吗？ ​

项目能开发 Vue2、JS、MyBatis Flex 等等版本吗？ ​

项目什么时候上 Cloud？ ​

项目有商业版吗？ ​

多次更换 UI 框架及模板说明 ​

后端 ​

🔥找不到某个 Bean 或访问接口提示 No endpoint ​

项目启动后，控制台报 machineId can't be greater than maxMachine[xx] or less than 0. ​

🔥代码生成的功能菜单 SQL 执行插入后，页面还是没有菜单，超管角色功能权限也没有该菜单权限还不能勾选 v3.4.0+ ​

🔥更新了数据库脚本后，启动项目报错 ​

使用 SSE 流式传输中断 <v3.7.0 ​

CrudController 添加了 @SaIgnore 注解不起作用 <v3.7.0 ​

在接口文档里，登录接口没有参数 v3.5.0+ ​

🔥我需要加一套对C端用户的接口，接口的鉴权如何处理？ ​

启动项目报错，转换 SaToken 类失败 v3.6.0+ ​

前端 ​

点击导出按钮报错 v2.5.0 ​

添加完菜单后路由不可用 v2.5.0 ​

配置好后端接口地址，接口 404 ​

网络控制台里请求的不是后端，是前端地址 ​

🔥使用 pnpm 10.x，启动后报错 The package may have incorrect... <v3.6.0 ​