本文详解 sqlite 中使用 `json_insert()` 函数配合 `$[#]` 语法安全、高效地向 json 格式存储的数组末尾追加新元素，解决 `json_set()` 动态索引失效导致的 `sqlite_range` 错误。
在 SQLite 中操作 JSON 数据时，一个常见误区是试图用 JSON_SET() 配合动态表达式（如 '$[JSON_ARRAY_LENGTH(comments)]'）来“自动计算索引并追加”。但 SQLite 的 JSON 函数不支持在路径字符串中嵌套 SQL 表达式——'$[JSON_ARRAY_LENGTH(comments)]' 会被当作字面量路径处理，而非运行时求值，最终导致索引越界（SQLITE_RANGE），因为 JSON_SET 无法识别该路径中的函数调用。
✅ 正确做法是使用 JSON_INSERT() 并指定特殊索引 "#"：
SQLite 的 JSON1 扩展明确规定，当路径中使用 $[#]（注意是英文井号 #，非数字）时，JSON_INSERT() 会自动将值插入到 JSON 数组的末尾，无需手动计算长度或处理边界情况。
以下是修复后的 Node.js + SQLite 示例代码：
app.post("/add-comment", (req, res) => {
const id = req.body.id;
const newComment = req.body.comment;
console.log("Adding comment: '%s' to articleID: %d", newComment, id);
global.db.run(
`UPDATE articles
SET comments = JSON_INSERT(comments, '$[#]', ?)
WHERE article_id = ?`,
[newComment, id], // 参数顺序：? → newComment，? → id
function (err) {
if (err) {
console.error("Failed to insert comment:", err.message);
return res.status(500).json({ error: "Database update failed" });
}
res.json({ success: true, message: "Comment added successfully" });
}
);
});? 关键要点说明：
- JSON_INSERT(comments, '$[#]', ?) 中的 $[#] 是 SQLite JSON 函数的保留语法，专用于数组追加，语义等价于“push”；
- 不要使用 JSON_SET() 实现追加——它仅用于替换现有索引位置的值，若索引超出当前数组长度，将直接报错；
- 确保数据库中 comments 字段初始值为合法 JSON 数组（如 [] 或 ["..."]），避免 NULL 导致 JSON_INSERT 返回 NULL；可添加默认值约束：comments TEXT NOT NULL DEFAULT '[]'；
- 若需初始化空数组，首次插入前可执行：UPDATE articles SET comments = '[]' WHERE comments IS NULL;
? 进阶提示：如需支持评论去重、时间戳、用户 ID 等结构化数据，建议将单字符串改为对象数组，例如：
[{"text":"great article","user":"alice","time":1717023456}]此时仍可用 $[#] 追加对象：JSON_INSERT(comments, '$[#]', json(?))（配合 json() 函数确保输入被解析为 JSON 对象）。
综上，牢记：追加用 JSON_INSERT(..., '$[#]', value)，替换用 JSON_SET(..., '$[n]', value)，切勿混淆语义与语法限制。
