在网页里生成紫微斗数星盘数据（iztro）

紫微斗数的排盘步骤比看上去多。阳历生日要先换算成农历，定命宫身宫，按年干起四化，再逐宫安主星、辅星、杂耀，还要处理庙旺利陷、三方四正，以及大限、流年、流月的顺逆。中间任何一处选错分界标准，整张盘就跟着偏。iztro 把这套流程收进一个 npm 包，用 TypeScript 写好类型，调用者拿到的是一组结构化对象，不是一张画好的图。

iztro 把紫微斗数排盘封装成可在 JavaScript 里调用的函数：传入出生日期、时辰与性别，返回十二宫星曜、四柱、运限和流耀，不用自己实现农历转换与宫位推算。

仓库在 https://github.com/SylarLong/iztro，MIT 许可证，主要语言 TypeScript，语言占比 99.5%。截至 2026 年 10 月，它有 4212 stars、682 forks、34 watchers，开放 issue 5 个，最近一次提交在 2026-10-08。下面按实际使用会遇到什么来组织：先列装上之后容易撞到的情况，再逐个拆开，然后分清哪些是库的限制、哪些是配置项，最后给绕开的做法和同类方案对照。

装上之后最先遇到的事

• 库只给数据，不给界面。README 在「直接使用」一节里写明，想零开发直接看排盘结果，请用紫微派（ziwei.pub）在线排盘。
• 排盘分界点存在流派差异。年份、月份、日期怎么切，默认值不一定符合你的习惯。
• 早晚子时的归属目前只有一种设定，晚子时被归入第二日，对应的 issue 至今标着「待解决」。
• 用独立 JS 文件引入时没有代码提示和注释。README 提醒，集成时请参阅开发文档。
• 多语言输出里的英文由作者意译，README 承认没有统一标准，只表示欢迎懂星象翻译的人提 PR。

逐个拆开看

晚子时归到哪一天

触发条件是用 bySolar 排盘，出生时刻落在子时。参数 timeIndex 接受 0 到 12，本命盘里农历日期和早晚子时都会显示出来。

表现是排盘时晚子时被直接归进第二日。有用户在 issue 里提出，晚子时的归属本身仍有争议，希望能加一个增强选项：一种保持现状，晚子时归入第二日；另一种让晚子时（23 点到 0 点）按当日排盘，早子时（0 点到 1 点）按第二日排。这条 issue 目前是待解决状态。

v2.6.1 修掉两处相关问题：horoscope() 显式传入早子时索引 0 时被误判为未传入、转而使用目标时间里的小时数；以及运限查询未遵守晚子时的日期分界配置。

流月按初一还是节气分

触发条件是在一个跨越立秋的农历月里查流月。市面上的排盘软件多以农历初一切分月份，这样七月里初一和立秋后几天的流月四化会算出不同结果。issue 里有人直接问过这个分界该按哪种。

这个已经解决。v2.5.5 把默认排盘月份改成按农历初一为分界，v2.5.4 把默认排盘日期改成按除夕为分界。如果所在流派不认这两个默认值，走全局配置覆盖。

排出来的八字或农历日期不对

触发条件集中在日期边界。有用户拿 1996-2-6 举例，说库排出的四柱是「乙亥 庚寅 癸酉 己未」，他认为年柱应当是丙子；另一位用户报告 1996-07-15 的农历换算结果和预期对不上。这两条 issue 都已经关闭。

v2.6.1 还修了一处虚岁计算：以生日为分界点时，后续年份在农历生日同月、生日之后会少算一岁。同版本修正了太阳、太阴和七杀在酉宫的亮度数据。

想要文字版的星盘汇总

触发条件是拿到排盘结果之后想直接喂给用户或语言模型。原来的输出是一张漂亮的图形，issue 提出希望有一个汇总接口，输出标明主星、辅星和庙旺利陷的文字版。

相关的两条需求都已关闭，一条是文字版汇总，一条是配合语言模型做文本交互。具体调用方式仓库正文没有展开，以 https://docs.iztro.com 的开发文档为准。

飞星流派的组合没有现成接口

触发条件是用飞星技法批量推算。issue 里要求把流年十二宫的诸星排列组合出禄忌关系，例如「命宫化忌入官禄冲夫妻」「本命化禄入夫妻，同时子女化忌入夫妻」，再把本命、大限、流年三盘的互相飞化列成表格输出。

这条 issue 仍然标着「待解决」。库提供的是单点判断能力，比如判断宫位是否产生飞星到目标宫位、获取宫位产生的四化宫位；组合层面的批量排布不在已有功能列表里。

哪些是限制、哪些是配置问题

属于设计限制的部分改不了。库只做计算不做渲染，npm 包交出来的始终是对象，想把它变成页面上的盘得自己画。奇门排盘不在这个库里，README 特别用提示框说明，奇门能力通过 API 和 Agents SDK 使用，不是本地排盘模块。英文等多语言翻译由作者意译，没有权威标准可依。独立 JS 构建产物没有类型提示和注释，这是打包形态决定的。星曜的别名反查也受语言版本约束，v2.6.1 才为韩文和越南语里的同名星曜补上带汉字的限定别名。

属于配置问题的部分有明确出口。年干分割点用立春还是除夕、日期与月份按什么切、四化和星耀亮度按哪一派，这些在 v2.3.0 引入的全局配置与第三方插件机制里可以覆盖，说明文档在 https://ziwei.pro/posts/config-n-plugin.html。托管 AI 模型和 Agents SDK 是另一回事，它们属于外部服务，要 API key，README 要求把密钥放在服务端环境变量 ZIWEI_API_KEY 里，并明确不要写进浏览器代码。

绕开的办法

1. 分界点和流派差异对不上时，别改源码，用 v2.3.0 起的全局配置覆盖，对照配置文档调参数。
2. 星曜按别名反查不到时，升级到 v2.6.1 或更高版本；该版本调整了武曲和岁破的英文名，分别改成 warrior 和 breaker，避免与将军、大耗重名。
3. 需要看得见的盘面时，React 项目可以直接用基于 iztro 的 react-iztro 组件；完全不写代码的人去 https://ziwei.pub 在线排盘。
4. 用独立 JS 版本、没有代码提示时，按 README 的提示对照 https://docs.iztro.com/quick-start.html 集成。
5. 早晚子时需要另一种排法时，issue 里提议的增强选项尚未提供，当前只有归入第二日这一种设定，这一项需要自行评估。

同类排盘方案横向对照

需要界面的时候 iztro 本身反而不是最优解。React 项目直接上 react-iztro 少写一层渲染，只想看盘的人在 ziwei.pub 或聊天机器人里问更省事，这两种场景下纯排盘库都多出一层要自己接的工作。iztro 的位置在需要拿到结构化数据、并且要在代码里控制查询逻辑的那一端。

适合用 iztro 的是这样几类人：在做自己的命理类产品、技术栈是 JavaScript 或 TypeScript、需要把十二宫星曜、四柱、运限、流耀当数据来查询和判断的开发者；需要按流派切换四化与亮度配置的开发者；需要同一份结果输出简繁英日韩越多语言的开发者。不适合的是想直接看一张盘、不打算写任何代码的人，用在线排盘站更快；技术栈不是 JavaScript 又只需要西方占星盘的项目，这个库帮不上，得另找对应语言的方案。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.2 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。