简介：Z80 ASM编辑器是一款专为经典8位处理器Z80设计的开源汇编开发工具，适合嵌入式爱好者、复古计算机玩家及计算机原理学习者使用，用于解决Z80汇编代码编写、调试与执行效率分析中的痛点。资源以zip压缩包形式发布，体积约23KB，共包含10个文件，其中8个JavaScript文件分别承担指令表、代码编辑、文件管理、日志记录等核心功能，2个HTML文件则提供便捷的浏览器操作界面。目前已有294人浏览学习。编辑器内置实时助记符信息、自动补全、断点调试与T状态分析等特性，能够直观展示每条指令的时钟周期与等待状态，帮助开发者快速定位性能瓶颈、优化代码结构。作为一个开源项目，它还允许使用者根据自身需求修改和扩展功能，无论是初次接触汇编语言的新手，还是经验丰富的开发人员，都能从中获得实用的编码辅助与学习参考。

1. 为什么还需要一个Z80 ASM编辑器：从复古硬件到现代嵌入式

你可能会觉得奇怪，都2029年了，谁还在用上古时期的8位处理器？可当我打开某开发者发来的求助信息，看到他在为一个自制8位电脑苦战，才发现Z80 ASM编辑器的需求从来没有消失，只是从大众视野退到了极客桌面。开源Z80 ASM编辑器，就是把汇编语言编写、交叉编译、模拟调试串在同一套工具链里的施工平台。它让复古计算机爱好者能复刻经典机器，让嵌入式开发者能精确控制启动引导代码的每一个时钟周期，也让计算机系统课程能在不折腾硬件的条件下看到寄存器如何闪烁。如果你正在折腾Z80，却还在用普通文本编辑器敲代码、到命令行敲编译、再手动打开模拟器，这篇笔记就是给你准备的。

2. 开源Z80 ASM编辑器选型：独立IDE、通用插件、命令行三类方案

选编辑器本质上不是比较按钮多少，而是选择一套工作流。你愿意装多个工具自己串联，还是希望打开一个窗口全包圆？开源Z80 ASM编辑器大致分为三类，每一类都对应不同的人群和项目阶段。先看懂取舍，再去下载配置，才能避免装上后觉得别扭又回头。

2.1 独立IDE型编辑器：开箱即用但绑定工具链

独立IDE型编辑器把所有功能打进一个安装包，启动后能看到项目树、代码区、编译按钮、模拟器面板和寄存器窗口。常见做法是新建工程时选择CPU型号为Z80，然后就能直接写代码点击运行。这类方案对完全没有命令行经验的复古游戏爱好者和学生非常友好，十分钟就能跑通一个点亮屏幕的示例，成就感来得很直接。

但缺点是绑定工具链。某开发者曾用某开源IDE做了个小游戏，模拟器里一切正常，导出ROM烧到自制主板上后完全不启动。排查半天发现IDE默认在二进制文件里加了一段512字节的文件头，而他的硬件仙力并没有这段。后来他改用通用编辑器加命令行汇编器，同样的代码一次通过。独立IDE适合只想在模拟器里玩一把的人，不适合要对接真实硬件或自研载入器的场景。

如果选择这条路线，我的建议是：做好心理准备接受它自带的文件格式和调试器接口，不要试图把它的输出直接交给其他工具链。查看项目的文档，确认导出格式是原始二进制还是带偏移的镜像，这一步能避免很多不必要的翻车。

2.2 通用编辑器插件：轻量灵活，推荐优先

更稳妥的做法是在一个成熟的开源代码编辑器上安装Z80插件。插件负责语法高亮、代码补全、构建任务注册和错误跳转，汇编和模拟仍调用外部独立工具。这样文件和工具链都是透明的，你和别人协作时，配置文件可以一起放进版本管理库，换台电脑几分钟就能重建环境。

我一般会选择这个方案，尤其面向多文件工程。当项目超过十个源文件时，独立IDE的项目树反而成了累赘，而通用编辑器的多光标编辑、全局搜索、书签和历史记录都是经过多年打磨的。Z80工程通常不大，几十个文件顶天，通用编辑器的性能绰绰有余。另外，你还可以把构建脚本、字符集转换脚本、烧录脚本都挂在同一个任务菜单下，形成真正属于你自己的开发流水线。

配置过程也不复杂，你要做的事情只有三件：装上插件、装上汇编器、写一个构建任务。这三件事第3章会完整演示。这里想强调的是，插件最好不要选那些捆绑自家模拟器的，否则你又退回到了上一类的绑定关系。理想状态是插件只管编辑体验，编译和运行完全由外部命令驱动。

2.3 命令行方案：最少依赖，适合脚本与CI

命令行方案最极端也最稳定：一个终端编辑器加一个汇编器，什么插件都不装。写代码用键盘，编译在另一个终端敲命令，出错就看行号。这种方案的优点是没有图形界面层的开销，远程开发非常友好，你完全可以借一台无头主机来编辑和编译，本地只负责查看结果。

缺点也很明显：没有符号跳转，没有自动补全，更没有内存可视化。但Z80汇编代码本身量不大，一个模块两三百行，通过集中注释和分段搜索也能应付。更重要的是，命令行方案天生适合自动化——持续集成、批量回归测试、夜构建都能把你平时在编辑器里点的按钮变成脚本里的几行命令。如果你正在为某个Z80模拟项目X写测试框架，命令行绝对是不可替代的基础形态。

三类方案对应不同阶段。我的习惯是：上手Demo用插件方案，进入开发阶段后用命令行脚本跑编译，调试时再用编辑器调试会话附加模拟器。它们的边界不是互斥的，你可以从A换到B，只要源文件不依赖于编辑器的私有格式，切换几乎没有成本。

3. 搭一个最小可用的Z80汇编开发环境：从安装到一键运行

这一章我们直接动手。环境搭建的目标是：能用一条命令把.asm源文件编译成二进制，并在模拟器里运行，同时让编辑器看得懂Z80语法。我先从工具安装讲起，再讲语法高亮配置，最后把编译和运行串成一个脚本。

3.1 安装汇编器与模拟器：先让“编辑”有“编译”可依

没有汇编器的Z80编辑器只能算记事本。常见的开源Z80汇编器是独立的命令行程序，支持输出原始二进制、符号表和列表文件。模拟器则是另一个独立程序，负责加载二进制并模拟Z80的CPU、内存和外设。安装方式取决于你的操作系统，这里演示在类Unix环境下的通用做法。

# 将下载的汇编器压缩包解压，假设已放到当前目录 tar -xzf z80asm-linux-x64.tar.gz # 把可执行文件放入用户目录并加入 PATH mkdir -p ~/bin cp z80asm ~/bin/ echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc source ~/.bashrc # 确认汇编器可执行 z80asm --version

这段命令做的事情是：解压工具包，把z80asm放到用户目录下的bin文件夹，并通过echo向环境配置文件添加一行PATH导出。执行source后，当前终端就能直接识别z80asm命令。参数说明：如果你的压缩包不是x64架构，请换成对应版本；如果系统提示找不到~/.bashrc，说明你用的不是bash，将同样的一行写入你所用shell的配置文件即可。

模拟器的安装方式完全一致，替换压缩包名称后，把可执行文件也放到~/bin。你可以用which z80sim验证。装好后，先写一个最小的Z80程序测试工具链是否能正常工作。

; hello.z80 ORG 0x8000 LD A, 42 loop: JR loop

编译并运行它：

z80asm -i hello.z80 -o hello.bin -l hello.map z80sim -m hello.bin -t 1000

这里-i指定输入源文件，-o指定输出二进制，-l生成符号表文件hello.map。-m告诉模拟器加载哪个内存镜像，-t 1000表示执行1000个时钟周期后自动停止。如果你的模拟器支持打印寄存器，你应该能看到A寄存器的值变成42，说明汇编和模拟都已跑通。

3.2 配置语法高亮与自动补全：拒绝黑白代码

通用编辑器不会平白无故识别Z80。你需要告诉它：哪些扩展名属于Z80、哪些助记符要上色、哪些伪指令需要特殊标记。大多数开源编辑器都支持通过配置文件或插件来定义语言。下面这份JSON是语言定义的核心结构，你可以直接复制到编辑器的语言配置项里。

{ "language": "z80", "extensions": [".asm", ".z80", ".s"], "keywords": ["LD", "JR", "JP", "CALL", "RET", "NOP", "DI", "EI", "RST"], "registers": ["A", "B", "C", "D", "E", "H", "L", "AF", "BC", "DE", "HL", "IX", "IY", "SP", "PC"], "directives": ["ORG", "EQU", "DB", "DW", "DEFB", "DEFW", "INCLUDE"] }

这个文件的作用是告诉编辑器的语法引擎如何分词。extensions决定哪些后缀的文件自动启用该语言；keywords是高亮的关键词列表；registers是寄存器名列表，有的编辑器会为寄存器单独配色；directives是伪指令，也就是编译时控制语句，比如ORG和EQU，它们通常被渲染成特殊颜色。

参数说明：.s扩展名在很多编辑器里被默认分配给其他处理器的汇编，如果你同时做ARM开发，建议把.s从列表中去掉，只用.z80或.asm。keywords里可以继续追加ADC、SBC、DAA等助记符，不要嫌多，铺得越全，一眼扫代码越省力。

配置保存后，重新打开一个.z80文件，代码应该不再是单调的黑白。如果编辑器支持代码片段，你还可以给常用指令配置缩写，例如输入lda按Tab直接展开成LD A,，这个小习惯能显著提高输入速度。

3.3 一键编译运行脚本：把手工操作变成一条命令

每次编译都要敲两行命令，用多了会烦。更好的做法是把编译和运行写成一个脚本，然后再把这个脚本挂到编辑器的构建任务上。这样你在编辑器里按一个快捷键，就能完成汇编、运行、看到输出结果的整个闭环。

#!/bin/bash set -euo pipefail # 第一个参数是源文件，默认 main.asm SRC="${1:-main.asm}" # 第二个参数是输出二进制，默认 main.bin OUT="${2:-main.bin}" # 调用 z80asm 汇编并生成符号表 z80asm -i "$SRC" -o "$OUT" -l "${OUT%.bin}.map" # 调用模拟器运行，-t 指定时钟周期数 z80sim -m "$OUT" -t 5000

这段脚本里的set -euo pipefail是bash的“后悔药”三件套：遇到错误立即退出、引用未定义变量时报错、管道中前一个命令失败也要退出。这样编译失败时你不会继续运行一个残缺的二进制。${1:-main.asm}表示取第一个参数，没传则用默认值。${OUT%.bin}.map是bash的字符串替换，把main.bin变成main.map，这样符号表文件名始终跟输出文件对应。

参数说明：-t 5000是我们的初始值。如果你的程序需要扫描键盘或等待某外设，5000个时钟周期可能瞬间就跑完并退出，模拟器会提示“timeout”。这时你应该把-t改成更大的值，或者切换到模拟器的交互模式。不要为了省事把周期数设成无穷大，遇到死循环你会卡到怀疑人生。

在编辑器侧，你需要告诉它“构建任务”存在。下面这段JSON是任务配置的可移植示例：

{ "tasks": [ { "type": "shell", "command": "./build.sh", "args": ["${file}", "${fileBasenameNoExtension}.bin"] } ] }

${file}是编辑器提供的占位符，代表当前打开文件的完整路径，${fileBasenameNoExtension}是不含扩展名的文件名。这样你打开hello.z80，按构建键，就会执行./build.sh hello.z80 hello.bin。如果你同时在多个终端或不同项目间切换，这个机制比手工切换窗口靠谱得多。

4. Z80汇编工程组织：内存布局、多文件与二进制资源

当项目从单文件成长到多文件，真正的麻烦才刚开始。Z80没有操作系统替你管理内存布局，也没有标准的链接器，一切都得靠汇编指令明确指定地址。这一章讲三个最容易出问题的工程组织环节：文件拆分方式、内存地址分配、二进制资源转换。

4.1 从单文件到多模块：INCLUDE与符号作用域

单文件程序写起来很快，但一旦超过几百行，翻页就在浪费生命。常见做法是把功能拆开：显示、键盘、音效各占一个.asm文件，主文件通过INCLUDE指令把其他文件的内容在编译时“贴”进来。这是一种文本级包含，不是真正的链接，所以被包含文件里的标签对主文件完全可见。

; main.asm ORG 0x8000 CALL init_screen CALL print_msg loop: JR loop ; 下面这句在编译时把另一个文件的内容插入到这里 INCLUDE "include/utility.asm"

这段代码里的INCLUDE会在编译时把include/utility.asm的全部内容原样插入到当前行位置。init_screen和print_msg这两个子程序在另一个文件里定义，由于是文本插入，主文件可以无条件调用它们。这也带来一个陷阱：如果被包含的文件里有ORG指令，它会把后续地址重置，导致主文件里loop标签的地址错乱，从而引发各种诡异跳转错误。

所以我在组织多模块时有一个铁律：只有主文件允许写ORG，所有被INCLUDE包含的文件一律不写地址，只写子程序和数据。这样做的好处是，整个工程的内存布局可以在主文件里一眼看全，哪个子程序落在哪个区域清清楚楚。

参数说明：INCLUDE的路径解析方式与汇编器实现有关，有的要求双引号、有的要求尖括号，有的把相对路径解释为相对于当前文件所在目录，有的解释为相对于汇编器工作目录。在你把项目交给别人前，最好先确认这一点，否则换台机器编译就报找不到文件。

4.2 内存布局与ORG指令：地址错位是最大的坑

Z80只有64KB地址空间，如何安排ROM、RAM、中断向量表、显存缓冲全由你决定。常见的8位家用机布局是ROM从0x0000开始，RAM从0x8000开始，中间还有各种外设寄存器地址。如果你在某个文件里多写了一个ORG，后面所有标签都会整体偏移，产生所谓“phase error”。

; main.asm ORG 0x0000 JP start ; 中断向量表，每个入口2字节 ORG 0x0038 JP int_handler ORG 0x0100 start: LD SP, 0xFFFF IM 1 EI ...

这段代码展示了一个标准的结构：0x0000处放一条跳转指令跳过向量区，0x0038是IM 1模式的中断入口地址，Z80在收到中断时固定跳到这里。0x0100才是我们自己代码的开始位置。注意JP start占3个字节，所以0x0038之前有充足空间，但如果你在0x0000写了ORG 0x0005，向量表就全被挤歪了。

遇到“address overlap”或“phase error”报错时，不要急着改代码，先检查每个文件的ORG。我自己的排错顺序是：先用编辑器查看符号表文件，找到出错标签的实际地址，再用十六进制工具打开二进制镜像，对比预期地址与生成地址。绝大多数地址冲突都能通过这步定位。

如果你使用支持链接脚本的汇编器，也可以把地址分配从源文件移到单独的配置文件里。但更常见的开源Z80汇编器依赖源文件内的ORG，所以多文件项目里一定要有人负责总体内存规划。我习惯在项目根目录放一张内存布局表，每加一个新模块就更新它，当作团队的共同记忆。

4.3 字符集与二进制资源：用脚本把字库变成DB指令

复古硬件往往没有文件系统，屏幕字体、图片、音乐序列都要以二进制数据形式烧进ROM。这些数据不能直接粘贴进汇编源码，最可靠的方式是用脚本把它们转换成DB指令。下面这段Python脚本演示了如何把一份8x16字库转成Z80汇编的数据段。

# 把二进制字库（每个字符16字节）转换成汇编 DB 语句 raw = open("font8x16.bin", "rb").read() lines = ["; 8x16 font data, 16 bytes per char"] for idx in range(0, len(raw), 16): chunk = raw[idx:idx+16] bytes_str = ", ".join(f"${b:02X}" for b in chunk) lines.append(f"; char #{idx // 16:02X}") lines.append(f"DB {bytes_str}") with open("font_data.asm", "w", newline="\n") as f: f.write("\n".join(lines) + "\n")

脚本的逻辑是：把整个字库文件按每16字节切块，每个块代表一个字符的像素数据。${b:02X}把每个字节格式化成类似$FF的十六进制字面量，并用逗号连接成DB语句的参数。注释里的char #00让最后生成的汇编文件可读性更好，方便你在源码里快速找到某个字符的数据。

参数说明：如果你的字库是8像素宽、1字节行宽，那么每个字符占8字节，而不是16。你只需要把代码里的两个16改成8即可。另外一个容易踩的坑是位序：Z80通常把字节的最高位对应像素最左边，但有些字库文件来自其他架构，位序是反的，生成前要先确认，否则显示出的字符都是水平镜像。

生成后的font_data.asm可以通过INCLUDE汇入主文件。在编辑器里，行数一下变多，但好处是资源数据纳入了版本管理，任何人改一个字模都能在diff里看得清清楚楚。这比维护一份单独的bin文件要直观得多。

5. 常见问题与避坑：Z80汇编开发中的五个血泪经验

开发Z80汇编和写现代高层语言最大的不同是，环境中的一个小意外可能毁掉一整天。下面这些坑我都遇到过，有的折腾了一晚上才醒悟。按“现象—原因—解决”的顺序整理，希望能帮你少走弯路。

5.1 语法高亮失效：扩展名被编辑器“劫持”

现象：你的.asm文件昨天还有颜色，今天打开全变成白色；或者高亮规则明显指向另一种处理器，比如把LD A, (HL)当成其他汇编语法标错。

原因：通用编辑器的语言关联把.asm和.s默认分配给了x86或ARM汇编插件，Z80插件无法同时接管同一个扩展名，优先级低的就被覆盖。

解决：把Z80源文件统一改为.z80扩展名，并在编辑器的语言关联配置里显式添加*.z80指向Z80语言。如果你保管着老代码且不想改文件名，可以手动打开文件后，在编辑器右下角语言模式里选择Z80，这样本次会话会被强制使用正确的高亮。长期项目还是建议统一扩展名，省心。

5.2 屏幕乱码：字符编码映射不一致

现象：编译运行后，屏幕显示的是花屏或问号，而不是你期望的“Hello”。

原因：你直接往显存里写ASCII码，但是目标平台的字符生成器并没有按ASCII顺序排列字符，或者字库压根没有加载到该显存地址。很多自制硬件都会自定义字符索引，A不一定是0x41。

解决：先写一个调试程序，循环向显存写入0x00到0xFF，用模拟器截图或实机照片得到实际的字符顺序。有了映射表后，在代码里加一个查表子程序，把输入的ASCII码转换成显存索引。不要迷信教科书上的标准字符表，你的目标平台说了算。

5.3 模拟器与实机结果不一致：时序的黑匣子

现象：模拟器上运行完美，烧到实机上后死机或画面错乱，在模拟器里怎么都复现不了。

原因：模拟器可能没有模拟等待状态、没有精确实现某条未公开指令的时序，或者中断请求的延迟与实机不同。Z80的代码经常依赖精确周期数，尤其是刷新显存和读取键盘的时候，一个周期不对就可能错一整帧。

解决：换成声称“周期精确”的模拟器，并确认它的配置打开完整中断模拟。接着逐段对照模拟器的trace日志与实机逻辑分析仪抓到的地址线数据，定位第一处差异。实在找不到差异，就减少对精确周期的依赖，给关键循环增加等待或改用由中断驱动的流程。

5.4 JR指令越界：相对跳转的范围限制

现象：汇编器报错“JR out of range”，明明代码看起来没问题。

原因：JR指令使用的是8位相对偏移，范围是-128到+127字节。程序规模变大后，原来的短跳转目标跑远了，越出了偏移范围。

解决：如果跳转距离不远，可以调整代码顺序让目标地址靠近；如果确实跨越了很长的代码段，把JR改成JP绝对跳转。要注意JP不修改条件标志，但它的执行周期比JR长，如果这段代码在时序关键路径上，你需要重新核算延迟。另一个常见做法是加一个中间标签，让JR先跳到一个近处，再用JP跳向真正目标，不过这多花代码空间，不推荐。

5.5 行尾符污染：Windows保存毁掉ROM镜像

现象：编译通过，烧录后系统完全无法启动。用十六进制编辑器打开镜像，发现文件末尾多了一个0x0D字节，或者整个文件的换行符都是0D 0A。

原因：很多文本编辑器在保存时自动使用CRLF行尾符，汇编器错误地把回车符当作一条有效指令的一部分，或者把它写进了最终输出。更危险的是，某些编辑器会在文件结尾自动添加一个换行符，而这个换行符在原始二进制面前就是多余的垃圾数据。

解决：在编辑器设置里强制默认行尾为LF，关闭“保存时自动追加最终换行”选项。对于已经损坏的项目文件，用dos2unix批量转换，并在转换后用十六进制工具确认首尾字节。如果你和同事协作，建议在工程根目录提交一个属性文件，强制所有源文件使用LF、禁止自动换行转换。这条血泪经验我踩了三次，每次都让我花几小时排查，希望你不要重蹈覆辙。

6. 更进一步：把调试与测试嵌进编辑器工作流

基础环境搭好、坑也填过，接下来可以做一些让日常开发更舒服的进阶配置。这一章聊两个方向：调试器接入和自动化测试覆盖，最后聊一个被很多人忽略的版本管理编码问题。

6.1 用调试协议连接模拟器：设断点、看寄存器

很多现代开源编辑器都支持统一的调试适配协议。如果模拟器实现了该协议，你就能在代码行号旁边直接点断点，在侧边栏看到寄存器值、内存内容和调用栈。给不支持的模拟器写一个适配器并不复杂，核心只是把模拟器的状态转换成协议消息。

class Z80DebugAdapter: def on_breakpoint(self, addr): self.sim.break_at(addr) return {"registers": self.sim.get_registers()}

这段伪代码展示了适配器的核心模式：断点命中后，读取模拟器寄存器并返回给编辑器显示。真正的适配器还需要处理单步、继续、读内存等请求，但思路是一样的。如果模拟器本身有trace文件输出，你也可以简单地把trace文件解析成文本信号，虽然没有图形调试，但好歹能自动定位到出错的那一条指令。

6.2 跑自动化测试：让每次修改都有验证

Z80汇编的bug往往藏在边界条件和标志位组合里，手工测试很难每天覆盖。常见做法是把测试断言写成汇编代码，在结尾把测试结果写入某个固定地址，再由模拟器读取作为退出码。写一个专门的测试入口文件，编译后跑模拟器，脚本就能自动判断全部用例是否通过。

#!/bin/bash set -euo pipefail # 编译测试套件 z80asm -i test_suite.asm -o test_suite.bin # 在模拟器中运行，-t 给足时间进入等待 z80sim -m test_suite.bin -t 100000 # 检查模拟器生成的退出标记 if [ -f "test_result.txt" ] && grep -q "PASS" test_result.txt; then echo "all tests passed" else echo "test failed, check test_result.txt" exit 1 fi

脚本的逻辑是：先编译测试程序，再用模拟器执行足够多的周期让程序自然跑完。测试程序内部会把比较结果写到一个模拟器支持的输出文件，脚本最后检查该文件里的PASS关键字来决定命令是否成功。把它接到持续集成系统里，每次提交代码后自动跑一遍，能大幅降低改动一个寄存器初始化顺序就弄坏显示函数的概率。

6.3 版本管理中的编码陷阱与我的最后一条经验

某次我在一个跨平台项目的仓库里提交了一份Z80字库数据源文件，在另一台电脑上克隆出来编译，生成的ROM在实机上花屏。查了很久，发现那份文件在提交时被自动转成了CRLF行尾符，里面恰好有某些字节被额外插入了0x0D，整段数据被污染。从那以后，我养成了一个习惯：每个Z80项目的第一条提交永远是一个编码规范文件，强制所有源文件使用UTF-8无BOM、行尾LF、不在末尾附加新行。这个动作虽然简单，却帮我挡住了大量从“编辑器魔法”里来的莫名bug。

如果你也在折腾Z80汇编，建议你把环境配置当作项目的一部分，而不是可有可无的细节。早期花十分钟固定这些规则，后面能省掉十几个小时的排错时间。希望帮到你。

本文还有配套的精品资源，点击获取