psql中文乱码需设客户端编码为utf8：连接时加--set=client_encoding=utf8，或进psql后执行set client_encoding='utf8'；导出需pg_dump --encoding=utf8；全文检索须用zhcn等中文分词配置并确认扩展已启用。
PostgreSQL客户端编码没设对，psql里查出来就是乱码
很多开发者在psql命令行里直接执行中文全文检索语句（比如SELECT * FROM mytable WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '测试');），结果返回一堆问号或方块——这不是Django的问题，是psql没用UTF-8解码响应。必须显式设置客户端编码：
- 连接时加参数：
psql -U postgres -d mydb --set=client_encoding=UTF8 - 进到
psql后立即执行：SET client_encoding = 'UTF8'; - 如果用
pg_dump导出含中文的全文索引数据，也得加--encoding=UTF8，否则导出文件本身已损坏
Django ORM里SearchVector和SearchQuery不认中文，返回空结果
默认PostgreSQL的simple或english文本搜索配置根本不支持中文分词，to_tsvector('english', '你好世界')会把整串当一个token，没法匹配。必须切换到支持中文的配置：
- 确认PostgreSQL已启用
zhparser或pgroonga扩展（不是只装了，还要CREATE EXTENSION） - 建表时指定中文分词器：
ALTER TABLE mytable ALTER COLUMN content TYPE tsvector USING to_tsvector('zhcn', content); - Django中不能硬写
'english'：SearchVector('content', config='zhcn')，否则ORM生成的SQL仍走英文规则 -
config值必须和PostgreSQL里pg_config列出的实际配置名一致，用SELECT cfgname FROM pg_ts_config;查，常见的是zhcn或chinese，不是随便写
Django模板或API接口返回JSON时中文变\u4f60\u597d或乱码
这通常不是数据库层问题，而是HTTP响应头或序列化环节漏掉了UTF-8声明：
-
JsonResponse默认带Content-Type: application/json，但不显式声明charset=utf-8；浏览器或某些旧客户端可能按ISO-8859-1解析——手动加：JsonResponse(data, json_dumps_params={'ensure_ascii': False}) - 如果用
HttpResponse返回自定义JSON字符串，必须设content_type='application/json; charset=utf-8' - 检查Nginx/Apache是否在响应头里覆盖了
charset，特别是启用了gzip压缩时，某些配置会删掉原有charset - Django
settings.py里的DEFAULT_CHARSET = 'utf-8'必须存在，且不能被中间件覆盖
PGroonga扩展安装后仍报错function "pgroonga_match_query" does not exist
PGroonga不是装完就自动可用，它依赖底层groonga引擎和正确的函数绑定：
- 确保以超级用户（如
postgres）身份在目标数据库执行：CREATE EXTENSION IF NOT EXISTS pgroonga; - 检查
pg_extension表：SELECT extname, extversion FROM pg_extension WHERE extname = 'pgroonga';，返回空说明没生效 - macOS用Homebrew装的PGroonga，要确认
postgresql@17和pgroonga版本兼容（例如PG 17.4 + PGroonga 4.0.1），版本错配会导致函数注册失败 - Django迁移里不能用
RunSQL直接调pgroonga函数，得先在数据库侧建好索引，再在ORM里用extra()或原生SQL调用
真正卡住人的地方，往往不是“没装扩展”，而是config名拼错、client_encoding没透传到连接池、或者HTTP响应头被反向代理悄悄改掉——这些点不打印日志根本看不出来。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
