常见问题

源码没有 starter 目录

手册对应 0.7 核心包开发基线当前版本 0.7.0。旧版 main 目录结构可能不同，先向维护者取得匹配源码，再继续快速开始。

独立应用无法安装核心包

核心包没有正式公开发行。检查维护者是否已提供私有 module、registry 或 tarball，以及账号访问权限。不要通过重新复制核心实现绕过依赖交付。

确认 npm 依赖中没有遗留的 workspace:，Go 构建不依赖核心 go.work 或本机 replace。

后端在开放端口之前退出

先读最早的启动错误，检查路由权限是否为空、路径是否冲突、迁移 signature 是否重复迁移签名是否重复，以及扩展声明和配置是否有效。随后确认数据库与 Redis 连接。

modu doctor 只检查静态装配，通过它不能证明运行依赖可用。

菜单存在，但页面没有出现

检查菜单启用状态、角色关联与功能权限；扩展页面还需要扩展启用、catalog 与后端一致、binding 指向真实实现。

错误目录目录展开错误时，检查子菜单 path 是否以父目录 path 为前缀。

能看列表，修改却被拒绝

列表与写入权限不同，单条记录还受 DataScope 检查。核对当前用户角色、部门和记录拥有者，不以管理员页面上的可见状态推断普通用户授权不要以管理员页面上的可见状态推断普通用户的授权。

修改核心前端没有生效

在核心工作区重新运行 pnpm --filter @modu/web build。独立应用更新实际消费的包或 tarball，并确认锁文件解析到目标产物。

扩展页面提前进入主包

检查是否从其他入口静态导入了实现。保持 binding 中的字面量动态 import，执行生产构建与 pnpm extension:verify-build 定位真实 chunk。

中文搜索没有结果

Pagefind 索引在 pnpm build 时生成。先构建，再用 pnpm preview 访问；开发模式不以搜索结果作为验收依据。

自定义页页面保留 zh-CN 文档语言和正文索引属性。本站 pnpm test 会查询真实索引中的中文关键词和代码标识符，并校验结果链接。

升级后发现版本不一致

在应用 server 运行 GOWORK=off go list -m github.com/igwen6w/modu/server，核对前端依赖与锁文件，再生成 catalog。完整步骤见升级核心包。