简介：面向初学 PHP 数据库操作的开发者，这份示例讲解如何通过 PHP 获取数据库表的字段名。内容围绕经典的 mysql_ 函数族展开，依次演示连接 MySQL 服务器、选择数据库、使用 mysql_list_fields() 列出字段、通过 mysql_num_fields() 统计字段数量，再配合循环与 mysql_field_name() 提取每个字段名并拼接输出。由于这套函数已在 PHP 7 中被移除，资源还介绍了 mysqli 与 PDO 中对应的字段获取方式，便于读者理解底层逻辑后平滑迁移到现代接口。压缩包为单个 PDF 文件，体积约 17KB，结构紧凑，适合快速阅读并在维护旧系统时作为技术参考。该示例已有 98 人学习，对处理动态数据表、构建查询语句或阅读历史代码的 PHP 开发者具有实用价值。
1. php获取字段名到底在解决什么问题：先看一个写死字段名的现场
某公司的后台管理系统里，业务列表页的表头一直是手写死在模板里的：数据库加一列，模板漏改，表头和数据就对不上。后来这个项目加了一个动态报表需求，才发现 php获取字段名 才是绕不开的第一步——从结果集里把列名动态拿出来，表头跟着查询走，导出 CSV 也少写几十行映射代码。这篇笔记把 mysqli、PDO、数组和对象四种取字段名的写法盘清楚，适合天天跟后台列表、报表导出、数据字典打交道的 PHP 开发者。下面先讲清楚为什么不能继续写死字段名。
2. 为什么不能写死字段名：三个场景与选型逻辑
2.1 动态表头：写死字段名为什么会翻车
先回忆最常见的后台列表页：SQL 是 SELECT id, title, status, created_at FROM 某张表，模板里直接放 id、title、status、created_at 四个表头。这个方案在最开始没有问题，因为字段和页面一一对应。问题出现在表结构变化的那一刻。某位同事把 status 拆成了 status_code 和 status_text，SQL 改了，模板表头没同步，结果页面上第三列还叫“状态”，显示的却是状态码的数字。用户看不懂，测试也发现不了。
更隐蔽的情况是字段顺序变化。数据库字段的物理顺序被调整后，查询直接用 SELECT *，页面表头还是旧的，但列顺序全乱了。这种错位比字段名写错更难排查，因为数据能显示，只是每一列的语义都错了。表头写死的本质是把“数据库结构”和“展示层”硬绑在一起，数据库一调整，展示层就要手工同步，漏一处就翻车。
反过来看动态获取字段名：SELECT 返回的字段列表本身就是最新的，把字段名拿出来做表头，字段顺序、个数、名称都跟着查询走，代码里没有第二份硬编码。这是我后来做后台管理系统时坚持“查询返回什么，表头就渲染什么”的直接原因。实现上无非是 mysqli 的 fetch_fields() 或 PDO 的 getColumnMeta()，哪种顺手用哪种。
2.2 导出 CSV 与 Excel：字段名映射的硬编码地狱
导出是另一个高频场景。导出一张订单表到 CSV，第一行一般是列头，也就是字段名。很多初版代码会写一个映射数组：中文列头 => 数据库字段名，导哪个表就写一份。十几个表就要维护十几份映射，字段调整时同步改映射。这还不是最痛苦的，痛苦在于导出和列表展示通常各写一套表头，列表页写死一套，导出脚本再写死一套，两个地方都可能漏改。
某次导出 Excel 时表头还是旧的，业务方拿着旧表头去核对数据，白白消耗半天时间。如果导出逻辑统一从结果集里获取字段名，再通过一个可选的“字段名 => 中文名”映射做翻译，映射表缺了某个字段时，至少字段名和顺序不会错，中文名往后补就行。这个思路下，获取字段名只是第一步，还需要一个翻译层：动态获取的字段名先过翻译层，有映射就显示中文名，没有映射就显示原始字段名。
这样导出表头永远不会和 SQL 结果对不上。翻译层用关联数组维护，键是数据库字段名，值是展示名。它仍然算“写死”，但写死的位置集中在一个配置文件里，字段变化时只改一处，而不是散落在每个导出脚本里。选型时记住一句话：字段名动态化解决的是“结构同步”问题，中文化解决的是“展示翻译”问题，两者别混在一起。
2.3 通用查询封装：字段名不写死的边界与代价
再往前走一步，就是封装一个通用查询组件。模拟项目X里要做一个数据字典页面，输入一条 SELECT，自动展示结果集的字段名、字段类型、字段长度。这个页面不关心具体是哪张表，所有信息都来自获取字段名这一步：mysqli 是 fetch_fields()，PDO 是 getColumnMeta()。拿到的字段对象里还带着类型和长度，正好用于数据字典展示。
但通用查询封装有一条边界：字段名动态化适合展示、导出、统计这类读场景，不适合业务逻辑强依赖固定字段的场景。状态字段的判断、金额字段的求和必须写死字段名，否则代码没法维护。另外，通用查询封装必须处理字段白名单。如果允许用户随便输入 SELECT，等于把整库数据暴露出来。我一般会做一个字段名白名单或表名白名单，只允许查询授权范围内的表和字段。
代价也在这里：白名单本身就是一种“写死”，但它写在权限配置里，而不是散落在模板和导出脚本里。配置集中的好处是改动有唯一落点，表结构频繁变化的系统里，集中式白名单反而比到处写死的字段名好维护得多。把三个场景连成一条链路：单页表头、导出映射、通用查询组件，复杂度逐步增加，字段名的获取方式是这条链路共同的底座。
3. 用 mysqli 和 PDO 抓取结果集字段名：完整示例与参数说明
3.1 mysqli 的 fetch_fields()：对象数组与字段属性
PHP 的 mysqli 扩展里，结果集对象有一个 fetch_fields() 方法，返回一个对象数组，每个对象对应查询结果的一列。对象里常用属性有 name（字段名）、orgname（原始字段名，不受别名影响）、table（表名）、type（字段类型）、length（长度）、flags（属性标记）。写出来是这样：
<?php $mysqli = new mysqli('127.0.0.1', 'user', 'pass', 'mock_db'); $mysqli->set_charset('utf8mb4'); $result = $mysqli->query('SELECT id, title, status FROM articles'); if ($result === false) { exit('查询失败: ' . $mysqli->error); } $columns = $result->fetch_fields(); foreach ($columns as $column) { echo $column->name . PHP_EOL; }这段代码先建连接，再执行查询，最后 fetch_fields() 拿到所有列。fetch_fields() 不需要参数，适合一次取全部字段名的场景。如果只想取某一列，可以用 fetch_field_direct(0)，参数是列索引，从 0 开始，比如只关心第三列就写 fetch_field_direct(2)。两者的性能差别可以忽略，但 fetch_field_direct 少一次数组分配，在频繁调用的场景里更省。
字段对象里的 type 是数值常量，MYSQLI_TYPE_LONG 代表整数型，MYSQLI_TYPE_VAR_STRING 代表字符串型。直接输出数字不直观，常见做法是把 type 和 flags 映射成可读文本，我在后面的数据字典示例里会展开。还有一个容易忽略的属性 orgname：当查询用了 AS 别名时，name 是别名，orgname 才是表里真实的列名，判断敏感字段时建议用 orgname。
3.2 PDO::getColumnMeta()：一条 SQL 拿回全部列信息
PDO 的写法更简洁，核心方法是 getColumnMeta($column)，参数是列索引。配合 columnCount() 循环一遍，就能拿到全部字段名：
<?php $pdo = new PDO('mysql:host=127.0.0.1;dbname=mock_db', 'user', 'pass', [ PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC, ]); $stmt = $pdo->query('SELECT id, title, status FROM articles'); $fieldNames = []; for ($i = 0; $i < $stmt->columnCount(); $i++) { $meta = $stmt->getColumnMeta($i); $fieldNames[] = $meta['name']; } print_r($fieldNames);getColumnMeta() 返回的数组，键名里有 name、table、native_type、pdo_type、len、flags。native_type 给的是驱动层原生类型，MySQL 下能看到 LONG、VAR_STRING 这类名字；pdo_type 对应 PDO::PARAM_* 常量；flags 是一个数组，包含 not_null、primary_key、auto_increment 这些标记，在 MySQL 上由驱动填充，不同驱动下 flags 的完整性不一样。
一个常见替代方案是先 fetch() 一行，再用 array_keys() 拿字段名。代码更短，但有个前提：结果集至少有一行数据。如果查询结果为空，array_keys 拿到的是空数组。getColumnMeta() 不依赖结果集是否有数据，空结果集也能拿到字段名，这是它在导出空表时报错场景里特别有用的原因。两种方式的取舍参考下面这张表：
| 维度 | mysqli fetch_fields() | PDO getColumnMeta() |
|---|---|---|
| 返回格式 | 对象数组 | 数组 |
| 空结果集 | 正常返回字段信息 | 正常返回字段信息 |
| 别名处理 | name 是别名，orgname 是原列名 | name 是别名，无 orgname |
| 额外信息 | type、flags、length、decimals | native_type、pdo_type、len、flags |
| 依赖 | mysqli 扩展 | PDO 对应驱动 |
在只有 mysqli 的老项目里，fetch_fields() 信息更全；在 PDO 统一管理多数据库的环境里，getColumnMeta() 写法更统一。两者不需要同时用。补充一个 PHP 8 环境下的注意点：getColumnMeta() 返回结构没有大变化，但 flags 在部分新版本驱动下从字符串数组变成数值标记，判断时别用等于号直接比较，建议用 in_array()。
3.3 从字段名到 HTML 表头：最小可运行示例
把上面的内容整合成一个函数，输入是 PDOStatement，输出是字段名数组，再配合循环就渲染出一个动态表头表格。关键点在于：字段名和行数据要从同一个 PDOStatement 上取，避免一条 SQL 执行两次：
<?php function getFieldNamesFromStmt(PDOStatement $stmt): array { $names = []; for ($i = 0; $i < $stmt->columnCount(); $i++) { $meta = $stmt->getColumnMeta($i); // 兜底：极少数驱动不返回 name 键时用占位名 $names[] = $meta['name'] ?? 'column_' . $i; } return $names; } $stmt = $pdo->query('SELECT id, title, status FROM articles'); $names = getFieldNamesFromStmt($stmt); $rows = $stmt->fetchAll(); ?> <table> <thead> <tr> <?php foreach ($names as $name): ?> <th><?= htmlspecialchars($name) ?></th> <?php endforeach; ?> </tr> </thead> <tbody> <?php foreach ($rows as $row): ?> <tr> <?php foreach ($names as $name): ?> <td><?= htmlspecialchars((string)($row[$name] ?? '')) ?></td> <?php endforeach; ?> </tr> <?php endforeach; ?> </tbody> </table>这段逻辑里，getFieldNamesFromStmt 先执行循环拿字段名，getColumnMeta 不会移动游标，所以随后 fetchAll() 能从第一行读到末尾。三条细节值得说明：一是 $meta['name'] ?? 'column_' . $i 兜底，个别驱动在极端情况下不返回 name 键，兜底保证循环不报错；二是渲染表头时用了 htmlspecialchars，字段名如果包含特殊字符，直接输出会被浏览器解析错；三是数据渲染用 $row[$name] 而不是位置索引，因为字段顺序和数组键名的对应关系不如字段名取值稳。
4. 获取字段名的避坑笔记：5 个真实翻车现场
4.1 非缓冲结果集没读完，第二条取字段名的查询直接报错
现象：某开发者在非缓冲模式下循环读大表，每行数据都处理正常。读到一半，业务逻辑里又执行第二条查询去拿另一张表的字段名，结果第二条查询直接抛 “Commands out of sync” 错误。
原因：MYSQLI_USE_RESULT 是非缓冲模式，行数据还留在服务端。连接上存在一个未取完的结果集时，MySQL 不允许在这个连接上发起新的查询，直到上一个结果集被取完或显式释放。取字段名本身不冲突，冲突的是“新查询”插队。
解决：非缓冲模式下，读取完数据后调用 $result->free()，或者干脆用默认缓冲模式。如果必须用非缓冲，就把字段名获取放到同一个结果集生命周期内，先取字段名再循环读数据，不要在一个结果集没结束时发起第二条 SQL。
4.2 别名里带中文或空格，字段名和你写的不一样
现象：SQL 里写 SELECT user_name AS 用户名称 FROM users，结果 getColumnMeta() 返回的 name 变成一串乱码，或者只有一个“用户”。
原因：MySQL 的别名里含中文或空格时，必须用反引号包起来，写成 AS用户名称。不带反引号时，MySQL 会把空格后面的内容当成另一个字段，别名被截断；字符集不对时，中文别名直接乱码。
解决：别名统一用英文加下划线，避免中文和空格。确实要中文表头时，放在展示层做字段名到中文名的映射，而不是靠别名闯关。这条规则对 mysqli 和 PDO 都适用。
4.3 getColumnMeta() 返回空 name：不同驱动的元数据完整度差异
现象：同一段代码在 MySQL 上正常，换成某个轻量测试库后，getColumnMeta(0) 返回的数组里没有 name 键，字段名全部丢失。
原因：getColumnMeta() 的实现在不同 PDO 驱动里完整度不同。MySQL 原生驱动支持得好，SQLite 也能给 name，但部分驱动或旧的预处理流程里，元数据没有被填充。官方对 getColumnMeta() 的定位是实验性接口，依赖它就要接受驱动的差异性。
解决：写一个兼容函数，先用 getColumnMeta() 取 name，取不到就退回到 fetch(PDO::FETCH_ASSOC) 拿第一行键名。两个方案都拿不到时，输出 column_0、column_1 这样的占位名，保证程序不中断。
4.4 大循环里反复调用 getColumnMeta()：性能黑匣子
现象：导出 5 万行 CSV，为了让每行的键名都“安全”，在循环体里对每一行数据都调用一次 getColumnMeta()，接口跑到一半直接超时。
原因：getColumnMeta() 每次调用都会重新解析结果集元数据，单次开销不大，但在数万次循环里会被放大成秒级延迟。这类问题表面像数据库慢查询，排查半天才发现是循环体里的元数据调用。
解决：字段名只获取一次，存到循环外部的变量里，循环体只做数组键名判断。这是“查询行为”和“渲染行为”分离的直接收益：查询阶段拿字段名，渲染阶段只消费字段名数组。血泪经验是：任何元数据操作都不要进循环。
4.5 SELECT * 把敏感字段名带进表头：白名单兜底
现象：通用查询组件上线后，某张表里新增了 is_internal 字段，这是内部标记，不允许出现在报表表头里，但动态获取字段名默认把它带了出来。
原因：动态获取字段名的代码不识别业务语义，SELECT 返回什么列，它就展示什么列。字段权限控制如果完全依赖代码里写死的字段名，动态化之后就会漏。
解决：在通用查询组件里加一层字段白名单过滤器。字段名数组拿到后，先跟白名单比对，不在白名单的字段直接过滤掉。白名单放在配置文件里，键是表名，值是允许展示的字段数组。这样动态获取字段名和权限控制就能共存，也算给敏感字段上了后悔药。
5. 从结果集走向数组与对象：字段键名获取的通用写法
5.1 array_keys() 与一维/多维数组的键名差异
数据库结果集转成关联数组后，字段名就变成了数组键名。取键名最直接的方式是 array_keys()。fetch() 取一行后，array_keys($row) 得到的就是这一行的字段名列表：
<?php $stmt = $pdo->query('SELECT id, title, status FROM articles'); $row = $stmt->fetch(PDO::FETCH_ASSOC); if ($row === false) { // 空结果集没有字段名可用，走 getColumnMeta 或直接中断 exit('no data'); } $fieldNames = array_keys($row);这个写法的优点是简单，缺点是强依赖“至少有一行数据”。空结果集时 $row 是 false，array_keys(false) 会暴露类型错误。多维数组场景要注意：fetchAll() 返回的是二维数组，array_keys($rows) 拿到的是数字索引 0、1、2，不是字段名。想拿字段名必须取第一行：$rows[0] 存在时 array_keys($rows[0])。
还有一个 PHP 7.3+ 才方便用的小技巧：array_key_first() 可以拿数组的第一个键，在“只需要第一个字段名”的场景里比 array_keys($arr)[0] 少一次数组拷贝。配合 empty() 判断空数组再取键，是处理空结果集更稳妥的写法。日常取字段名时，我习惯把这段逻辑包在一个函数里，和结果集元数据做双保险。
5.2 对象属性与 JSON：字段名在对象场景下怎么取
PHP 里字段名不只存在于数组里。ORM 返回的对象、接口返回的 JSON，都有“字段名”问题。最常见的是 get_object_vars()：
<?php class Article { public $id; public $title; private $status; } $article = new Article(); $article->id = 1; $article->title = 'demo'; $vars = get_object_vars($article); // 在类外部调用，private 属性 status 不会出现在 $vars 里 print_r(array_keys($vars));get_object_vars() 的可见性规则经常让人翻车：在对象外部调用时，只返回 public 属性；在类内部调用时，返回当前作用域可见的属性，包含 private 和 protected。如果要在外部拿全部字段，必须配合反射，这个下一节展开。
JSON 场景更直接：json_decode($json, true) 转成关联数组后，array_keys() 拿到的就是 JSON 的键名，这在做第三方接口字段校验、动态渲染接口文档时非常实用。注意 json_decode 的第二个参数必须传 true，否则返回的是对象，就得用 get_object_vars() 再转，多绕一层。
5.3 反射与 ORM：字段名到属性名的最后一公里
当字段名藏在对象私有属性里时，需要反射来兜底。ReflectionClass 的 getProperties() 可以列出所有属性，再用 getName() 取出属性名：
<?php $ref = new ReflectionClass(Article::class); foreach ($ref->getProperties() as $prop) { echo $prop->getName() . PHP_EOL; }这样能把 private 属性名也列出来，但要注意：反射拿的是“类结构里声明的属性名”，不代表数据库字段名。一些 ORM 会把数据库字段名映射成驼峰式属性名，比如数据库里的 created_at，对象属性叫 createdAt，这时拿到的属性名需要经过命名风格转换才能反推字段名。
因此我的建议是：能走结果集元数据，就拿结果集元数据；ORM 对象的属性名只用于业务层。数据字典、表结构导出这类需求，直接在数据库层解决，不要让 ORM 的属性命名规则参与进来。反射属于“兜底手段”而不是常规手段，能不用就不用，这是维护成本上的核心判断。
6. 进阶：字段名缓存与动态报表组件的收尾技巧
6.1 字段名缓存：一次查询换取多次复用
动态报表组件里，同一张表可能被多个页面调用。如果每次渲染都先查一次字段名，再查一次数据，SQL 数量翻倍。我的习惯是加一个静态变量缓存：
<?php function getFieldNamesCached(PDO $pdo, string $sql): array { static $cache = []; $hash = md5($sql); if (isset($cache[$hash])) { return $cache[$hash]; } $stmt = $pdo->query($sql); $names = []; for ($i = 0; $i < $stmt->columnCount(); $i++) { $meta = $stmt->getColumnMeta($i); $names[] = $meta['name'] ?? 'column_' . $i; } $cache[$hash] = $names; return $names; }这个缓存的粒度是整个请求生命周期：同一个 SQL 在同一请求里只解析一次字段名。表结构经常变的系统不要跨请求缓存，静态变量只对当前请求生效，正好适合页面内部多次调用的场景。请求结束后缓存自动清空，不会和数据库里的结构变更产生长时间不一致。
6.2 PHP 8 命名参数与字段映射的清爽写法
字段名拿到后，经常要做“数据库字段名 => 展示字段名”的映射。PHP 8 的命名参数配合映射数组，能把这段映射代码写得很干净。例如定义 formatHeader($field, $zhName = '')，调用时用 formatHeader(field: 'status', zhName: '状态')，只传需要覆盖的字段，其他字段用原始字段名。这个写法不改变逻辑，只是让调用处的意图更清楚。
我现在的习惯是：所有取字段名的操作都收口到一个方法里，调用方永远只拿字段名数组，不直接碰 getColumnMeta() 或 fetch_fields()。遇到上面写的那几个坑时，排查点也只有一个。这个习惯帮我省掉过好几次半夜排查接口超时的麻烦，也希望帮到你。
本文还有配套的精品资源，点击获取
