vCardのURLにバックスラッシュが残る理由 エスケープとCRLF

連絡先を QR コードや .vcf ファイルで渡す vCard は、1行に「名前:値」を並べただけの単純な形式に見える。ところが値の中にカンマやセミコロンが入ると、書き方とパーサーの組み合わせで結果が変わる。

この記事では、ハシトシステムの 連絡先QRコード生成 と CSV→vCard(.vcf)変換 が出力する vCard 3.0 を例に、次の3点を確かめる。

  1. URL の値にもエスケープをかけると、バックスラッシュが残るパーサーがある
  2. JavaScript で '\;' と書いたエスケープは、セミコロンをエスケープしていない
  3. 改行が LF だけだと読めないパーサーがある

検証環境は Windows 11、Node.js v24.11.1(ical.js 2.2.1、vcf 2.1.2)、Python 3.11.9(vobject 0.9.9)である。

vCard 3.0 のエスケープ規則

vCard 3.0 は RFC 2426(1998年)、その土台の書式は RFC 2425 で決められている。値の型によってエスケープの扱いが違うのが要点である。

プロパティ RFC 2426 での値の型 エスケープ
FN NOTE TITLE など text \\ \; \, \n を使う
N ADR ORG 構造化された text(; で区切る) 区切りでない ; は \; にする
URL uri text のエスケープは定義されていない

text の文法は RFC 2426 の付録で次のように書かれている。

1
2
text-value   = *(SAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR)
ESCAPED-CHAR = "\\" / "\;" / "\," / "\n" / "\N")

一方 URL は「A single uri value」とされ、text ではない。URI の中のカンマやセミコロンは RFC 3986 で使ってよい文字なので、そのまま書くのが本来の形である。

ORG が構造化されている点も重要である。RFC 2426 の ORG は「組織名;部署1;部署2」のように ; で階層を区切る。会社名そのものに ; が入っていてエスケープされていないと、2つ目以降は部署名として読まれる。

vCard 4.0(RFC 6350、2011年)では 3.4 節で、N や ADR のような複合プロパティの中の ; は必ずエスケープ、そうでないプロパティでは「エスケープしてもよい(MAY)」と整理された。

改行についても RFC 2425 と RFC 2426 の文法は、各行を CRLF で終えると決めている。

2つのツールの出力

2026-11-18 に本番の HTML を取得し、エスケープ関数を取り出して Node.js で動かした。

入力 連絡先QRコード生成 CSV→vCard変換
Hashito;R&D Hashito\;R&D Hashito;R&D
Hashito, Inc. Hashito\, Inc. Hashito\, Inc.
https://example.com/?q=a,b;c(URL 欄) https://example.com/?q=a\,b\;c https://example.com/?q=a\,b;c
行の区切り LF CRLF

CSV→vCard変換の関数には「カンマ・セミコロン・バックスラッシュ・改行をエスケープする」というコメントがあり、コードは次のとおりである。

1
2
3
4
5
6
7
function esc(v){
return String(v == null ? '' : v)
.replace(/\\/g, '\\\\')
.replace(/;/g, '\;')
.replace(/,/g, '\\,')
.replace(/\n/g, '\\n');
}

3行目だけ '\\;' でなく '\;' になっている。JavaScript の文字列リテラルで \; は特別な意味を持たない文字のエスケープとして扱われ、ただの ; になる。つまり ; を ; に置き換えているだけで、何もしていない。strict モードでもエラーにならないので気付きにくい。

1
2
$ node -e "console.log('\;' === ';')"
true

3つのパーサーで読む

同じ vCard 3.0 を、エスケープと改行を変えて ical.js・vcf・vobject に読ませた。ORG は Hashito;R&D、NOTE は 月;水 在席、URL は https://example.com/?q=a,b;c を入れたつもりのデータである。

ケース ical.js 2.2.1 vcf 2.1.2 vobject 0.9.9
A: 全部エスケープ・LF ORG 正しい / URL に \ が残る エラー ORG・URL とも正しい
B: 全部エスケープ・CRLF ORG 正しい / URL に \ が残る 値をそのまま返す (A と同じ)
C: '\;' の書き間違い・CRLF ORG が Hashito と R&D に分かれる 値をそのまま返す ORG が Hashito と R&D に分かれる
D: URL は %2C %3B・CRLF すべて正しい 値をそのまま返す すべて正しい

分かったことは次のとおりである。

  • URL のエスケープ: ical.js は URL を uri 型として扱い、\, を戻さない。結果は https://example.com/?q=a\,b\;c で、このままブラウザに渡すとクエリが変わる。vobject は URL も text と同じように戻すので a,b;c になる。パーサーによって答えが分かれる書き方は避けたほうがよい
  • '\;' の書き間違い: ORG は構造化された値なので、ical.js も vobject も Hashito を組織名、R&D を部署名として読む。NOTE は構造化されていないので、エスケープが無くても 月;水 在席 のまま読めた
  • ical.js の NOTE: エスケープした 月\;水 在席 が、ical.js では \ を残したまま返った。ORG の \; は正しく戻しているので、構造化されていない text の \; だけ戻さない動きである。RFC 6350 では構造化されていないプロパティの ; のエスケープは任意なので、NOTE では ; をエスケープしないほうが、どのパーサーでも同じ結果になる
  • LF だけの改行: vcf は Unsupported version "ARD" というエラーで読めなかった。ical.js と vobject は LF でも読めた
  • vcf の値: vcf 2.1.2 の valueOf() はエスケープを戻さず、ファイル上の文字列をそのまま返す。使う側で戻す必要がある

URL にカンマやセミコロンを入れたいときは、D のようにパーセントエンコード(, は %2C、; は %3B)にすると、エスケープの解釈に関係なく全パーサーで同じ文字列になる。ただし %2C と , はサーバーによって別の値として扱われることもあるので、もとの URL が動くかは確かめる。

ツールの修正点

確かめた結果、次の点を修正対象として記録した。

  • CSV→vCard変換: .replace(/;/g, '\;') を .replace(/;/g, '\\;') に直す。会社名や氏名に ; が入ると、ORG や N の区切りがずれる
  • 2つのツールとも: URL に text のエスケープをかけない。カンマやセミコロンを含む URL は、そのまま書くかパーセントエンコードにする
  • 連絡先QRコード生成: 行の区切りを LF から CRLF にする。RFC の文法どおりにし、厳しいパーサーでも読めるようにする

QR コードに入れたときに読み取り側のスマートフォンがどう扱うかは、今回は確かめていない。ここでの結果は上記のライブラリでの実測である。

同じように1行に「名前:値」を並べる iCalendar の折り返しとエスケープは、ICSの75オクテット折り返しで日本語が化ける理由とセミコロンの書き忘れ で調べている。

実際に試す

前提: Node.js(確認は v24.11.1)と Python 3(確認は 3.11.9)。空のディレクトリで実行する。

まず Node.js で、ical.js と vcf に同じ vCard を読ませるスクリプトである。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// vcard-parse.mjs(Node.js v24.11.1 + ical.js 2.2.1 + vcf 2.1.2 で確認)
// 使い方: npm install ical.js@2.2.1 vcf@2.1.2 && node vcard-parse.mjs
// 同じ vCard 3.0 を、改行(LF / CRLF)とエスケープを変えて2つのパーサーに読ませる
import ICAL from 'ical.js';
import vCard from 'vcf';

// RFC 2426 の text 値のエスケープ(\ ; , 改行)
const esc = (s) => s.replace(/\\/g, '\\\\').replace(/;/g, '\\;').replace(/,/g, '\\,').replace(/\n/g, '\\n');
// よくある書き間違い: '\;' は JavaScript では ';' と同じ文字列になる
const escTypo = (s) => s.replace(/\\/g, '\\\\').replace(/;/g, '\;').replace(/,/g, '\\,').replace(/\n/g, '\\n');

const org = 'Hashito;R&D';
const url = 'https://example.com/?q=a,b;c';
const build = (e, urlValue, eol) => [
'BEGIN:VCARD', 'VERSION:3.0', 'N:山田;太郎;;;', 'FN:山田 太郎',
'ORG:' + e(org), 'NOTE:' + e('月;水 在席'), 'URL:' + urlValue, 'END:VCARD',
].join(eol) + eol;

const icalRead = (text) => {
const c = new ICAL.Component(ICAL.parse(text));
const v = (p) => JSON.stringify(c.getFirstProperty(p).getValues());
return `org=${v('org')} note=${v('note')} url=${v('url')}`;
};
const vcfRead = (text) => {
try { const c = new vCard().parse(text); return `org=${JSON.stringify(c.get('org').valueOf())} url=${JSON.stringify(c.get('url').valueOf())}`; }
catch (e) { return 'ERROR ' + e.message; }
};

console.log("'\\;' === ';' :", '\;' === ';');
for (const [label, text] of [
['A esc+URLもesc LF ', build(esc, esc(url), '\n')],
['B esc+URLもesc CRLF', build(esc, esc(url), '\r\n')],
['C escTypo CRLF', build(escTypo, escTypo(url), '\r\n')],
['D esc+URLは%xx CRLF', build(esc, url.replace(/,/g, '%2C').replace(/;/g, '%3B'), '\r\n')],
]) {
console.log(`[${label}]`);
console.log(' ical.js', icalRead(text));
console.log(' vcf ', vcfRead(text));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$ node vcard-parse.mjs
'\;' === ';' : true
[A esc+URLもesc LF ]
ical.js org=["Hashito;R&D"] note=["月\\;水 在席"] url=["https://example.com/?q=a\\,b\\;c"]
vcf ERROR Unsupported version "ARD"
[B esc+URLもesc CRLF]
ical.js org=["Hashito;R&D"] note=["月\\;水 在席"] url=["https://example.com/?q=a\\,b\\;c"]
vcf org="Hashito\\;R&D" url="https://example.com/?q=a\\,b\\;c"
[C escTypo CRLF]
ical.js org=[["Hashito","R&D"]] note=["月;水 在席"] url=["https://example.com/?q=a\\,b;c"]
vcf org="Hashito;R&D" url="https://example.com/?q=a\\,b;c"
[D esc+URLは%xx CRLF]
ical.js org=["Hashito;R&D"] note=["月\\;水 在席"] url=["https://example.com/?q=a%2Cb%3Bc"]
vcf org="Hashito\\;R&D" url="https://example.com/?q=a%2Cb%3Bc"

出力は JSON.stringify なので、\\ は実際の値では \ 1つである。C の ical.js の org が二重の配列になっているのは、組織名と部署名の2つに分かれたことを表している。

次に Python の vobject で同じデータを読む。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# vcard_parse.py(Python 3.11.9 + vobject 0.9.9 で確認)
# 使い方: pip install vobject==0.9.9 && python vcard_parse.py
import vobject

def card(org, note, url, eol):
lines = ['BEGIN:VCARD', 'VERSION:3.0', 'N:山田;太郎;;;', 'FN:山田 太郎',
'ORG:' + org, 'NOTE:' + note, 'URL:' + url, 'END:VCARD']
return eol.join(lines) + eol

cases = {
'A esc+URLもesc LF ': card(r'Hashito\;R&D', r'月\;水 在席', r'https://example.com/?q=a\,b\;c', '\n'),
'C escTypo CRLF': card('Hashito;R&D', '月;水 在席', r'https://example.com/?q=a\,b;c', '\r\n'),
'D esc+URLは%xx CRLF': card(r'Hashito\;R&D', r'月\;水 在席', 'https://example.com/?q=a%2Cb%3Bc', '\r\n'),
}
for label, text in cases.items():
c = vobject.readOne(text)
print(f'[{label}] org={c.org.value} note={c.note.value!r} url={c.url.value!r}')
1
2
3
4
$ python vcard_parse.py
[A esc+URLもesc LF ] org=['Hashito;R&D'] note='月;水 在席' url='https://example.com/?q=a,b;c'
[C escTypo CRLF] org=['Hashito', 'R&D'] note='月;水 在席' url='https://example.com/?q=a,b;c'
[D esc+URLは%xx CRLF] org=['Hashito;R&D'] note='月;水 在席' url='https://example.com/?q=a%2Cb%3Bc'

Windows のコンソールで日本語が化けるときは、先に set PYTHONIOENCODING=utf-8(PowerShell なら $env:PYTHONIOENCODING='utf-8')を実行する。

vCard を書き出すときの注意

  • text の値(FN NOTE など)と構造化された値(N ADR ORG)は、\ ; , 改行をエスケープする。\ を最初に置き換える
  • JavaScript で置換後の文字列を書くときは '\\;' と2つ重ねる。'\;' は ; そのものになる
  • URL には text のエスケープをかけない。カンマやセミコロンが入る URL は、パーセントエンコードにすると解釈の違いが出ない
  • 行は CRLF で区切る。LF だけだと読めないパーサーがある
  • 書き出したファイルは、少なくとも2種類のパーサーで読み戻して確かめる

まとめ

  • vCard 3.0(RFC 2426)では、text の値にだけ \; \, のエスケープが定義され、URL は uri 型である。
  • URL にエスケープをかけると、ical.js 2.2.1 ではバックスラッシュが残り、vobject 0.9.9 では戻る。パーサーで答えが分かれる。
  • JavaScript の '\;' は ; と同じで、セミコロンをエスケープしたつもりでも何も変わらない。構造化された ORG では組織名が2つに分かれた。
  • 改行が LF だけの vCard は、vcf 2.1.2 ではエラーになった。
  • ハシトシステムの2つの vCard ツールには、これらに当たる箇所があり、修正対象として記録した。

結果は 2026-11-18 時点の上記の環境とツールの実装で得たものである。

参考

  • RFC 2426「vCard MIME Directory Profile」(1998年9月)3.5.5 ORG、3.6.8 URL、4. Formal Grammar の text-value と ESCAPED-CHAR
  • RFC 2425「A MIME Content-Type for Directory Information」(1998年9月)5.8.1 Line delimiting and folding(行の区切りは CRLF)
  • RFC 6350「vCard Format Specification」(2011年8月)3.4 Property Value Escaping、6.7.8 URL
  • ical.js 2.2.1、vcf 2.1.2、vobject 0.9.9 での上記スクリプトによる実測
  • ハシトシステム 連絡先QRコード生成・CSV→vCard(.vcf)変換の本番 HTML(2026-11-18 取得)

vCardのURLにバックスラッシュが残る理由 エスケープとCRLF
https://blog.hashito.biz/2026/11/18/vcard-30-escape-url-backslash-semicolon-crlf-ical-js-vobject/
著者
hashito
作成日
2026年11月18日
著作権

このバージョンはその範囲に入るのか

依存の話でいちばん間違えやすいのは ^1.2.3 や ~1.2.3 がどこまでを許すかです(^0.2.3 のようにメジャーが 0 のときは規則が変わります)。範囲とバージョンを貼ると、下限・上限に展開したうえで一致・不一致とその理由を表示するsemver 範囲判定ツールを置いています。ブラウザの中だけで動き、入力はどこにも送信しません。