常见问题

源码没有 starter 目录

核心仓库根目录包含 starter/（内含 server/ 与 web/），供核心工作区联合开发使用；独立开发包直接提供 server/、web/ 和应用工具，不需要 starter/。按快速开始下载 0.13.0 开发包；不要使用 GitHub 自动生成的 Source code 附件代替开发包。

独立应用无法安装核心包

核心包已私有发布。在线安装需要 igwen6w/modu 仓库和 @igwen6w/modu-web 包的读取权限。首次执行 core:install 时指定 npm registry、实际 npm 包名和 Go direct 来源；完整命令见快速开始。

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

私有 npm 包返回 403

确认使用 GitHub Classic PAT，包含 read:packages，账号也具有包读取权限。重新执行 pnpm core:login 保存凭据，再在同一应用目录重试安装；CI 可通过 MODU_NPM_TOKEN 环境变量注入。

Go 下载认证失败

执行 gh auth status 确认账号，再执行 gh auth setup-git --hostname github.com 配置 Git HTTPS 凭据助手。应用的 Go 操作使用根目录的 pnpm server:go，例如 pnpm server:go list -m github.com/igwen6w/modu/server。

安装中断或留下 .modu-update

首次安装失败时保留应用目录，修正原因后重试，不重新解压覆盖应用。已有应用升级失败时先按失败恢复恢复；若留下 .modu-update/，先运行 node scripts/online.mjs restore，不要直接删除备份目录。

app:setup 或 dev:all 命令不存在

0.13.0 开发包自带包括 app:setup、app:upgrade、dev:all 在内的全部 Node ESM 模板命令。若当前应用由 0.7.1 及更早的 Python 工具模板创建，先执行 core:tooling-upgrade 迁移到 Node ESM 工具；core:upgrade 升级核心依赖不会自动更新模板工具，详见版本说明与升级核心包。

数据库端口被占用

独立应用默认使用 PostgreSQL 55432、Redis 56379。初始化前同步修改应用 docker-compose.yml 的宿主机端口及 server/.env 中的 DB_PORT / REDIS_PORT；Docker 连接失败时先确认 Docker 已启动。

后端在开放端口之前退出

先读最早的启动错误，检查路由权限是否为空、路径是否冲突、迁移签名是否重复，以及扩展声明和配置是否有效。随后确认数据库与 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 会查询真实索引中的中文关键词和代码标识符，并校验结果链接。

升级后发现版本不一致

在应用根目录运行 pnpm server:go list -m github.com/igwen6w/modu/server 和 pnpm --dir web list @modu/web --depth 0，核对实际配套版本与锁文件，再生成 catalog。完整步骤见升级核心包。