简介MajsoulPaipuAnalyzer 是一套面向雀魂四人麻将玩家的牌谱分析工具支持国服、日服与国际服并提供 Windows、Linux、macOS 多平台版本。分析项目参考天凤牌谱解析程序实现已覆盖除被鸣牌和门清听牌两类外的多数统计维度结果网页还附带天凤凤凰桌牌谱数据便于玩家横向对照自身牌局表现需注意修罗模式牌谱可能暂无法解析。压缩包共 74 个文件约 1.18MB以 14 个 JavaScript 文件承担页面与分析交互、8 个 C 与 9 个头文件实现核心算法若干 JSON/YML/HTML/CSS 组织配置和结果展示另含 GIF、PNG 图示及 Markdown 说明文档整体结构清晰。目前已有 6663 人学习下载适合希望复盘牌效、比较不同规则数据并研究工具实现的中高级麻将玩家参考。1. 从一份打不开的牌谱说起装之前先把环境对齐MajsoulPaipuAnalyzer 这类雀魂牌谱分析工具的安装翻车点常常不在代码而在浏览器。我第一次装的时候压缩包解压、依赖也装了双击目录里那个 HTML 入口页面干干净净一片白控制台第一行就是跨域请求被拦——那一刻才反应过来这套东西不是双击就能用的桌面程序而是一个必须挂在本地 HTTP 服务上的网页应用。牌谱分析这件事本身不复杂把对局记录导出来工具读进去统计和牌率、放铳率、副露率、立直后的和牌率、平均顺位、局收支最后拼出一份 HTML 报表。适合的人也明确——想复盘自己牌谱、又不愿意把对局数据往别人服务器上传的玩家以及要给一堆牌谱做批量统计的人。装不好的典型后果就三种页面空白、数据读不进去、报表永远显示 0 局。下面这份安装笔记按「先定 Python 版本 → 建虚拟环境 → 装依赖 → 配牌谱目录和本地 HTML 服务 → 排错 → 验证」的顺序走新手照着敲能跑通熟手可以只看版本取舍和避坑那两章。2. 装 Python 与虚拟环境3.10 和 3.11 到底差在哪一步这一章只干一件事把 Python 定下来并且把它关进一个独立的虚拟环境里。牌谱分析脚本的依赖不重但一定会碰到 numpy、pandas 这类带 C 扩展的包版本选错后面几章全是补丁。2.1 版本怎么定3.9 到 3.12 的取舍这类工具的技术栈一般很朴素读 JSON、做统计、渲染 HTML。真正影响安装成功率的不是语法特性而是依赖包有没有现成的二进制 wheel。版本优势主要风险我的选择3.9兼容性最广老机器自带部分新版本分析库已不再发 3.9 的 wheel装到一半转源码编译只在系统自带、且不方便升级时用3.10结构模式匹配、类型标注完善生态成熟少数新库开始把 3.10 作为最低版本而非首选稳妥备份方案3.11解释器性能提升明显numpy/pandas 有完整 wheel个别老版本依赖还没跟上首选3.12最新特性齐全C 扩展包缺轮子容易现场编译失败暂不用于部署我一般锁 3.11既有完整的二进制包又不会因为太新而在pip install阶段现场编译。如果所在机器只有 3.10也不用折腾升级3.10 跑这套分析逻辑完全够。先确认机器上有什么# 看默认版本和路径避免装完发现用的还是系统那个 3.9 python3 --version which python3 # Windows 用 where python python3 -c import sys; print(sys.executable)三条命令分别回答「版本是多少」「命令指向哪个可执行文件」「Python 自己认为它是谁」。第三步最关键——很多「我明明装了 3.11」的情况都是命令指向了系统自带的旧版本。按平台装指定版本# macOSHomebrew brew install python3.11 /opt/homebrew/bin/python3.11 --version # Debian / Ubuntu sudo apt update sudo apt install -y python3.11 python3.11-venv python3.11-dev build-essential python3.11 --versionWindows 直接用官方安装包安装向导第一步务必勾上Add python.exe to PATH装完在 PowerShell 里用py -3.11 --version验证py启动器能同时管理多个版本比改 PATH 干净。Linux 上python3.11-venv这个包必须单独装它不在标准库里。这是我在 Debian 系上遇到的第一个坑python3.11 -m venv直接报ensurepip is not available报错信息完全没提「你缺一个包」。2.2 建虚拟环境把依赖关进笼子不要往全局环境里pip install。原因很实在牌谱分析工具对 pandas/numpy 的版本要求和你机器上其它项目经常打架一旦全局升级坏的是别人的项目而你几天后才发现。# 进到工具目录的上一级venv 建在项目里删项目就等于删环境 cd ~/tools python3.11 -m venv .venv # 激活macOS / Linux source .venv/bin/activate # 激活Windows PowerShell # .venv\Scripts\Activate.ps1 # 激活后必须复核这两个指向 python -V pip -Vpython -m venv .venv里-m venv表示调用标准库的 venv 模块.venv是目录名带点表示隐藏目录也方便被.gitignore一类的规则忽略。激活的本质是临时改PATH把.venv/bin放到最前面所以激活后python和pip都应该指向.venv里面。pip -V的输出里带不带.venv路径是判断有没有真正激活的唯一硬标准。我习惯把虚拟环境建在项目根目录而不是外面好处是路径短、迁移时一起打包代价是重装项目要重建环境。分析类工具迭代不频繁这个代价可以接受。退出用deactivate。关掉终端窗口不会自动清理环境变量之外的残留下次进来记得重新激活别在没激活的状态下装包——装完发现「依赖明明装了却 import 不到」八成就是这个。2.3 源、缓存和装依赖前的三项自检pip默认源在部分网络环境下会超时表现是ReadTimeoutError或者卡在Collecting不动。改源是常规操作# 换成能连通的镜像源只影响当前用户 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config list # 顺手把构建工具升上去很多「装不上」其实是 setuptools 太老 pip install -U pip setuptools wheelpip config set会把配置写进用户级配置文件pip config list用来确认真的写进去了。setuptools和wheel一定要先升级老版本 setuptools 处理pyproject.toml时会报一堆看不懂的backend错误而报错文本里根本不会提「你的 setuptools 太老」。装依赖前我固定做三项自检比事后翻日志省时间磁盘空间。df -h ~至少留 2GBpandas 加 numpy 的 wheel 解压后并不小。编译工具链。真要现场编译时Linux 需要build-essential和python3-devmacOS 需要xcode-select --installWindows 需要 Visual Studio Build Tools 的 C 工作负载。网络连通。pip download --no-deps -d /tmp/probe pandas能下下来就说明源没问题下不下来就是网络或镜像的事别在依赖版本上瞎猜。3. 落盘与装依赖requirements 里最容易卡住的两类包代码到手之后有两件事要做把它放到一个「干净」的路径下以及按正确的顺序把依赖装完。这两步的失败率加起来比后面所有配置加起来都高。3.1 解压路径别让空格和中文进路径# 统一放在 ~/tools 下目录名保持和压缩包一致 mkdir -p ~/tools cd ~/tools unzip ~/Downloads/MajsoulPaipuAnalyzer.zip -d MajsoulPaipuAnalyzer cd MajsoulPaipuAnalyzer ls -la-d指定解压目标目录解压完ls -la是为了确认目录结构能直接看到requirements.txt、HTML 入口文件、配置文件的这一层就是项目根目录。很多压缩包会在外面再套一层同名目录解压完变成MajsoulPaipuAnalyzer/MajsoulPaipuAnalyzer/requirements.txt后面所有命令的路径都要多一层非常容易出错。路径里的空格和中文是硬伤。虚拟环境的激活脚本、pip 读取的 requirements 路径、以及部分 C 扩展的构建脚本对空格的处理并不一致表现是No such file or directory但文件明明就在那。Windows 上更明显C:\Users\张三\Desktop\新建文件夹\这种路径几乎必然出问题。我一般会先把它挪到D:\tools\MajsoulPaipuAnalyzer这种纯英文短路径下再动手。目录结构确认之后再建虚拟环境回第 2 章顺序不要反先建 venv 再解压也行但 venv 一定要建在你最终要用的那个路径里中途挪目录会让激活脚本里的绝对路径全部失效。3.2 装依赖先只装轮子失败了再逐个来# 第一步只允许二进制包不编译。能过就说明环境干净 pip install --only-binary:all: -r requirements.txt # 第二步上一条失败时带日志装方便定位是哪个包炸的 pip install -r requirements.txt -v install.log 21 tail -n 60 install.log--only-binary:all:是个很实用的开关它强制 pip 只使用预编译好的 wheel不允许现场编译源码。这个参数的价值在于快速暴露问题——如果它能过说明整条链路没有编译依赖后面基本不会再有环境问题如果它卡住报错会直接点名是哪个包没有对应平台的 wheel而不是在一堆编译输出里淹死。-v加日志重定向是为了事后能查。终端里的滚动输出会被后面的报错冲掉落到文件里才能grep -i error install.log。我通常还会先单独装两个大头# 先装数值计算底座它们的 wheel 最大、最容易失败隔离出来单独排查 pip install numpy1.24,2.0 pip install pandas2.0,3.0 # 底座就位后再装剩下的 pip install -r requirements.txt把 numpy 和 pandas 单独拎出来的理由它们是这套分析里最重的两个包也是唯二有可能触发编译的包。版本区间写成1.24,2.0而不是固定死一个版本是因为牌谱统计只用到基础的数据结构操作不需要最新特性锁死大版本可以避开 numpy 2.x 那轮 ABI 变更带来的连锁问题。依赖装完做一次导入自检比直接启动程序更早发现问题python -c import numpy, pandas; print(numpy.__version__, pandas.__version__)能打印出版本号就说明动态库加载正常。Python 层面import成功但运行时报DLL load failed的情况多半是同一个环境里混进了别的 Python 的库路径或者 Windows 上缺 VC 运行库。3.3 装不上时的降级策略真碰到编译失败不要在原命令上反复重试按这个顺序降级换 wheel 版本。报Failed building wheel for xxx时先看这个包有没有更早的、带 wheel 的版本。pip install 包名版本号逐个试比装编译器快得多。补编译环境。Linux 上sudo apt install build-essential python3-devmacOS 上xcode-select --installWindows 上装 Build Tools 的「使用 C 的桌面开发」工作负载。临时降 Python。如果某个包死活没有当前版本的 wheel说明它还没跟上把 Python 降到 3.10 通常能解决这比跟编译器搏斗省时间。还有一个容易被忽略的点requirements.txt里有时会带-e .或者git开头的行这类依赖会触发源码安装而且需要联网拉取。装不上时先看一眼文件内容把这类行注释掉再试能快速判断问题是不是出在它们身上。4. 牌谱目录与本地 HTML 服务先解决 file:// 白屏依赖装完最想做的事就是双击 HTML 看效果。这一步恰恰是整套安装里翻车最集中的地方因为它和前几章的 Python 环境没半点关系。4.1 牌谱放哪目录结构先定下来工具的输入是牌谱文件输出是 HTML 报表两头都是目录最好在启动前就把结构定死# 在项目根目录下建两个目录输入和输出 mkdir -p data/paipu reports # 把自己的牌谱文件放进去一个对局一个文件 cp ~/Downloads/*.json data/paipu/ ls -l data/paipu/ | headdata/paipu是输入目录reports是输出目录分开建的好处是重跑分析时只要清空reports就行不会误删原始牌谱。牌谱这类原始数据删了就得重新导出属于典型的「后悔药没处买」所以我习惯把输入目录单独备份一份。文件名建议直接用牌谱 ID保持纯 ASCII扩展名统一.json。中文文件名在部分编码环境下读出来是乱码报错信息会变成UnicodeDecodeError排查方向直接被带偏。关于文件格式这类工具的输入一般是导出的对局记录 JSON常见的顶层字段大致是牌谱标识、玩家列表、局数与每局的行动序列具体字段名各版本可能不同以实际导出的文件为准。有一个通用检查# 确认编码是 UTF-8且文件开头没有 BOMBOM 会让 json.load 直接失败 file -i data/paipu/*.json head -c 3 data/paipu/第一个文件.json | xxdfile -i看编码声明head -c 3配合xxd看前三个字节。如果是efbbbf说明文件带 BOMPython 的json.load会在第一个字符就报Expecting value: line 1 column 1——这个报错看起来像文件是空的实际只是多了三个不可见字节。Windows 上记事本另存的 JSON 特别容易带 BOM用编辑器另存为「UTF-8 无 BOM」即可。4.2 起一个本地 HTTP 服务别再双击 HTML# 在项目根目录执行绑定回环地址只允许本机访问 python -m http.server 8000 --bind 127.0.0.1然后浏览器打开http://127.0.0.1:8000/index.html入口文件名以项目实际为准。为什么必须起服务现代浏览器对file://协议下的fetch、XMLHttpRequest有严格限制页面通过脚本去读同目录的 JSON 时会被判定为跨域并直接拦掉。表现就是第 1 章那个场景——HTML 打开是白屏控制台一条红字页面本身没有任何问题。python -m http.server把目录挂成一个 HTTP 站点同源策略就不再拦这些请求了。--bind 127.0.0.1这个参数值得单独说。不加它服务默认监听所有网卡同一局域网内的其它机器能直接访问你的牌谱数据。牌谱里带着对局记录和玩家标识没必要对外绑回环地址是最省事的隔离方式。提示http.server是标准库自带的开发用服务器单线程、无缓存控制。分析几千份牌谱时页面加载会偏慢但它足够稳定也不需要额外装任何东西本地单人使用完全够。4.3 端口和配置文件改哪几行改完同步哪里8000 被占用是常事换端口只需改一个数字但要记得浏览器地址跟着改# 被占用时换 8080也可以先用 lsof 看看是谁占的 lsof -i :8000 python -m http.server 8080 --bind 127.0.0.1如果项目自带配置文件把路径和端口写进去避免每次启动都靠命令行参数{ paipu_dir: ./data/paipu, output_dir: ./reports, port: 8000, encoding: utf-8 }字段含义依次是牌谱输入目录相对项目根目录用相对路径方便整体迁移、HTML 报表输出目录、本地服务端口、文件读取编码。相对路径是相对于启动进程时的当前工作目录不是相对于配置文件所在目录——所以一定要在项目根目录执行启动命令在别的目录下执行./data/paipu就会指向别处报表出来是 0 局而日志里可能什么都不报。这是我认为最隐蔽的一个坑。改完端口后有两处要同步一是浏览器访问的地址二是如果配置里还有别的字段引用了这个端口比如报表里内嵌的资源地址一并核对。5. 避坑与排查五条装坏了的现场记录下面五条都是「装完但跑不起来」的真实类型按现象、原因、解决三段写。看到相似现象直接对号入座不用从头再捋一遍流程。5.1 环境层的三个坑坑一error: Microsoft Visual C 14.0 or greater is required现象Windows 上装依赖编译到一半红字退出提示缺 C 编译工具。原因某个包在当前 Python 版本下没有预编译 wheelpip 退回到源码编译而机器上没有 MSVC 工具链。解决优先换版本而不是装编译器——pip install 包名更早的版本找到有 wheel 的那个版本。实在没有装 Visual Studio Build Tools勾选「使用 C 的桌面开发」装完重开终端再执行。这属于血泪经验先花两分钟找 wheel比花半小时装三个 G 的编译器划算。坑二激活了虚拟环境pip -V却还指向全局现象source .venv/bin/activate执行没报错python -V是 3.11但pip install装完python -c import 包名依然找不到。原因shell 里存在pip的别名或函数覆盖或者PATH里别的位置排在.venv/bin前面。解决type pip看它到底指向谁echo $PATH看顺序。最省事的做法是永远用python -m pip install代替裸pip它会强制使用当前python对应的那个 pip绕开所有别名问题。坑三ensurepip is not available现象Linux 上python3.11 -m venv .venv直接失败提示 ensurepip 不可用。原因Debian 系把 venv 拆成了独立包标准安装里不含。解决sudo apt install python3.11-venv。如果还不行补python3.11-dev。别去手动改 ensurepip 的源码那条路只会越走越远。5.2 运行层的两个坑坑四双击 HTML 白屏控制台报跨域现象页面完全空白F12 里一条Access to fetch at file:///... from origin null has been blocked by CORS policy。原因file://协议下页面的 origin 是null读取本地 JSON 被同源策略拦截。解决回到项目根目录执行python -m http.server 8000 --bind 127.0.0.1用http://127.0.0.1:8000/index.html访问。注意地址栏里要出现http://只要还是file:///就说明没走服务。坑五服务起来了报表却显示 0 局现象页面能打开界面正常但所有统计都是 0也没有明显报错。原因三种可能——启动命令不在项目根目录相对路径失效牌谱目录指向的文件夹是空的JSON 带 BOM 导致逐个解析失败而程序把失败静默跳过了。解决按顺序查。先pwd确认当前目录再ls data/paipu | wc -l确认文件数量最后用python -c import json; json.load(open(data/paipu/某个文件.json, encodingutf-8))单独验一个文件能不能解析。第三步能直接暴露 BOM 和字段缺失问题。这个排查顺序是从外到内比一上来就读源码快得多。6. 验证跑通三步冒烟缺一步都不算装完装完不等于跑通。我验证这套工具固定走三步每步都有明确的失败信号任何一步不对就停在那一步不往下走。第一步确认服务真的在监听# 看端口有没有进程占用-I 只取响应头不下载页面内容 lsof -i :8000 curl -I http://127.0.0.1:8000/index.htmlcurl -I返回HTTP/1.0 200 OK说明静态服务正常。返回Connection refused就是服务没起来回到第 4 章返回404说明路径对但文件名不对ls看一眼入口文件到底叫什么。Windows 上没有curl的用浏览器直接打开地址能出页面就算过。第二步确认数据被吃进去了# 看输出目录里有没有新生成的文件时间戳要是刚刚 ls -lh reports/reports里出现带当前时间戳的 HTML 文件说明读取、解析、渲染这条链路通了。目录是空的但页面正常通常是牌谱目录配错按坑五的顺序查。第三步看数字对不对检查点正常表现异常时的指向对局数和data/paipu里的文件数一致有文件被静默跳过查 BOM 和字段和牌率、放铳率在 0 到 100 之间的合理值统计口径或玩家标识匹配出错顺位分布四项之和等于总对局数中途流局或数据缺失的局没被计入单局收支有正有负能对上一个具体半庄分数换算或规则配置和实际玩法不一致对局数这一行最值得盯。它和文件数对不上说明有文件没解析成功而这类工具通常在解析失败时不中断只跳过——这是个黑匣子式的静默失败不主动核对根本发现不了。我一般会在第一次跑完之后手动挑一个牌谱把里面的和牌次数、放铳次数对着报表数一遍对上了才认为这套环境可信。顺手留一份环境快照下次重装能少走一半路# 冻结当前环境的所有包版本重装时直接照着来 python -m pip freeze requirements.lockfreeze输出的是精确版本号包括那些间接依赖。和requirements.txt里的区间约束不同它记录的是一份「已验证可用」的快照。换机器时先pip install -r requirements.lock能复现出一模一样的环境等确认没问题了再回头处理主依赖文件的版本区间。从那以后我每次装这类带 HTML 前端的分析工具都会强制先起本地服务、再用curl -I打一次响应头确认是 200 才去点开页面——这个动作只花十秒但省掉过我至少三次「到底是我装错了还是页面本身坏了」的自我怀疑。希望帮到你。本文还有配套的精品资源点击获取