紫微斗数排盘引擎教程-开源免费的命盘工具,本地就能算

导语：ziwei-doushu 是一款免费开源的紫微斗数排盘引擎，基于倪海厦《天纪》体系，包含完整排盘算法、四化系统、格局知识库和古籍原文数据，无需 API Key，本地就能排盘。本文是面向普通用户和开发者的完整上手教程。

项目地址：https://github.com/Renhuai123/ziwei-doushu

一、它是什么？

ziwei-doushu 是一个开源的紫微斗数排盘引擎。通俗地说，它是一套”帮你自动画出命盘”的程序——你输入出生年月日时和性别，它就能算出一张紫微斗数命盘，把十二宫、主星、四化、神煞等都排出来。

它有几个特别的地方：

• 基于倪海厦《天纪》体系：排盘口径参照了倪海厦先生的紫微斗数讲解，适合学习或认同《天纪》体系的人。
• 算法完整且严谨：包含完整的排盘算法、四化系统、格局知识库，还内置了古籍原文数据。
• 免费、无需 API Key：排盘、命盘展示、合盘起盘全都在浏览器本地完成，不依赖任何付费接口。

打个比方：传统排盘要么靠师傅手排，要么用闭源的商业软件。这个项目相当于把”排盘的底层算法”开源出来，让任何人都能自己跑、自己查、自己二次开发。

二、它到底有多火？

这是一个增长很快的开源项目（以下数据来自 GitHub 仓库实时统计，截至 2026 年 10 月 31 日）：

• Star 数：约 1.2 万（star 可理解为”收藏/点赞”，说明有上万开发者或用户主动收藏了它）。
• Fork 数：约 2300（fork 是”复制到自己账号”，代表有不少人在它的基础上做二次开发）。
• 诞生与更新：仓库创建于 2026 年 5 月 1 日，最近一次推送就在 2026 年 10 月 31 日——半年时间破万 star，且更新频繁。
• 主要语言：TypeScript，前端和 Node.js 生态的主流语言。

能在半年内获得上万 star，说明它在”传统文化 + 技术开源”这个细分领域确实切中了真实需求。

三、核心功能有哪些？

• 完整排盘算法：支持十二宫、主星、辅星、四化（化禄、化权、化科、化忌）、神煞等的自动排布。
• 真太阳时校正：会根据出生地的经度差和均时差做校正，让排盘更准确。
• 中国夏令时处理：内置 1986–1991 年中国夏令时的自动换算。
• 农历/公历互转：支持农历与公历的互相转换，并正确处理闰月边界。
• 星曜亮度流派数据：提供《斗数全书》等不同流派的亮度对照表，可切换。
• 古籍原文数据：内置倪师《天纪·紫微斗数》原话 1848 条，方便对照学习。
• 回归测试与 CI：内置 768 盘 × 紫微铁律的排盘回归测试，保证算法稳定。

四、三步上手指南（面向开发者详细版）

这个项目有两种用法：普通用户直接在线用，开发者本地跑起来。下面分别说明。

方式一：普通用户——直接在线排盘（最简单）

项目作者提供了在线站点（README 中提到的 ouranic.cn），普通用户无需安装任何东西，直接打开网站输入出生信息即可排盘。如果你只是想排一张命盘看看，走这条路最省事。

方式二：开发者——本地跑起来

如果你想自己部署、二次开发，或者不想依赖在线服务，可以按下面的步骤在本地运行。

第 1 步：克隆仓库

先确保电脑装了 Node.js（推荐较新版本），然后打开命令行，输入：

git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu

解释：git clone 是把代码下载到本地，cd 是进入项目目录。

第 2 步：安装依赖

npm install

解释：安装项目运行所需的各种依赖包。

第 3 步：启动

如果只是本地看排盘，跳过环境变量配置，直接启动：

npm run dev

启动后，在浏览器访问终端里提示的地址（通常是 http://localhost:3000），就能看到排盘界面了。

如果想验证引擎是否正确，可以跑测试：

npm run typecheck   # TypeScript 全量类型检查
npm test            # 排盘引擎回归测试

关于 AI 解读功能

需要特别说明：开源版不含后端 API 路由。排盘、命盘展示、合盘起盘都在浏览器本地完成，不需要任何 API Key。但 AI 解读（/api/interpret）和合盘 AI 分析（/api/heming）这两个功能，需要你自己实现对应的接口；没实现之前，这两处会提示”开源版不含该接口”，即使配置了 API Key 也不会生效。

五、哪些人适合用？

• 紫微斗数学习者和爱好者：想免费排盘、对照倪海厦《天纪》体系学习的人。
• 命理研究者：需要一个算法透明、可验证、可对照古籍的排盘工具。
• 开发者：想把排盘能力嵌入自己的应用、小程序或网站，做二次开发的人。
• 注重隐私的人：排盘在本地完成，出生信息不出本机。

六、哪些人不建议用 / 需要避坑

• 想开箱即用”AI 自动解盘”的人：开源版不含 AI 解读接口，需要自己实现，纯小白可能无法直接用上 AI 解读功能。
• 完全不懂命令行、也不想部署的人：直接在线用即可，不必碰本地部署。
• 注意流派差异：项目默认星曜亮度采用《斗数全书》口径，但之前默认的”现代修正 v2″仍可在流派设置里切换；不同流派排盘结果可能略有差异，学习时注意对照。
• 维护节奏：作者明确说明这是一个”排盘引擎 + 数据集的开放快照”，不是全职维护的商业产品，issue 回复可能不及时。
• 理性看待命理：紫微斗数属于传统文化范畴，排盘结果仅供学习参考，请理性看待，勿盲目迷信。

七、常见问题排查（新手必看）

问题 1：npm install 报错或安装失败

含义：通常是 Node.js 版本过旧，或网络无法访问 npm 源。

解决办法：先升级 Node.js 到较新版本；再检查网络，必要时切换 npm 镜像源。

问题 2：启动后页面打不开

含义：服务可能没启动成功，或端口被占用。

解决办法：确认 npm run dev 的终端还开着、没报错；按终端提示的地址访问。

问题 3：AI 解读功能点了没反应

含义：开源版不含 AI 解读接口。

解决办法：这是设计如此，不是 bug。需要你自己实现 /api/interpret 接口才能用。

问题 4：想验证排盘结果准不准

含义：想确认引擎输出是否正确。

解决办法：运行 npm test，它会跑 768 盘 × 紫微铁律的回归测试，覆盖夏令时、立春边界、红鸾天喜、时辰序号等场景。

八、总结

ziwei-doushu 是一个增长很快的开源紫微斗数排盘引擎，基于倪海厦《天纪》体系，算法完整、无需 API Key、本地就能排盘，且内置了 1848 条倪师原话语料和回归测试。它适合紫微斗数学习者、命理研究者和想二次开发的程序员。

如果你对 AI 相关的工具也感兴趣，可以看看本站之前介绍的《REA 教程》等更多开源项目。最后提醒：排盘结果仅供学习参考，请理性看待命理。